devcontour-harness 0.0.0-stage → 0.1.0-alpha.6

package/docs/contracts.md

@@ -0,0 +1,603 @@
+# Договоры devcontour-harness
+
+Источник истины — Zod-схемы в `src/contracts`. TypeScript-типы экспортируются
+из `devcontour-harness` и `devcontour-harness/contracts`.
+
+## JSON Schema и семантическая проверка
+
+`schemas/<имя>.schema.json` генерируется из тех же схем (`npm run schemas`);
+`npm run check` падает, если закоммиченные файлы устарели, а тест паритета
+сверяет вердикты Zod и JSON Schema (Ajv, draft 2020-12) на положительных и
+отрицательных примерах.
+
+Harness не нормализует значения: строки вроде `title`, `goal`, критериев и
+значений ресурсов обязаны быть уже без пробелов по краям — правило выражено
+регулярным выражением и одинаково в Zod и JSON Schema.
+
+Программная проверка доступна из `devcontour-harness`: `validateInputs`
+(то же, что `harness validate`) и отдельные функции ниже.
+
+JSON Schema выражает всё, что относится к одному значению: типы,
+обязательность, закрытость объектов, пределы, регулярные выражения путей и
+refs, варианты исходов. Связи **между** значениями проверяются только
+функциями пакета и `harness validate`:
+
+| Функция         | Что проверяет                                                                                                                |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `graphIssues`   | Повтор ID, неизвестная зависимость, цикл графа                                                                               |
+| `policyIssues`  | Циклы компонентов и gates, test gate у репозитория, ресурсы, профили инструментов, `effort`, `fixture`, пары writer/reviewer |
+| `crossIssues`   | Связь поручений с политикой: роль, ресурсы, область записи и доказательства, требования, потребители, предпосылки            |
+| `contextIssues` | Содержимое снимка контекста совпадает с digests и пределами                                                                  |
+| `reviewIssues`  | Ответ reviewer согласован с историей находок предмета                                                                        |
+
+Опубликованы: `work-order`, `work-graph`, `execution-policy`,
+`context-snapshot`, `contract-document`, `run-result`, `result-envelope`,
+`run-event`, `review-record`, `joint-verification`, `execution-document`.
+
+## Версии
+
+| Версия        | Значение                           | Поле / константа            |
+| ------------- | ---------------------------------- | --------------------------- |
+| Пакет         | `0.1.0-alpha.N` до стабильного API | `HARNESS_VERSION`           |
+| Публичный API | `devcontour-harness/v1alpha1`      | `apiVersion`, `API_VERSION` |
+| Политика      | `1`                                | `policyVersion`             |
+| Состояние     | `1`                                | `stateVersion`              |
+
+Версии независимы. Пакет читает только перечисленные в
+`SUPPORTED_*_VERSIONS`; неизвестная версия входа, политики или состояния
+отклоняется до любой мутации и до выдачи claim. Для `0.x`: patch — совместимые
+исправления, minor — отдельно описанные изменения договора, включая
+несовместимые. Выпущенная версия неизменяема.
+
+Digests (`workGraphDigest`, `policyDigest`, `sourceDigest`, `findingId`) —
+SHA-256 канонического JSON (`canonicalJson`: ключи по порядку, `undefined`
+опускается). Формула — часть договора; тесты закрепляют эталонные значения.
+
+## Входы
+
+### WorkOrder
+
+Исполняемое поручение — снимок постановки, а не редактируемая задача. Лишние
+поля отклоняются: поручение не несёт статуса, результата или согласования.
+
+| Поле               | Смысл                                                                                                                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `apiVersion`, `id` | Версия договора и ID                                                                                                                                                                                                     |
+| `source`           | `{connector, ref, revision}` — откуда и какая редакция                                                                                                                                                                   |
+| `title`, `goal`    | Название и цель                                                                                                                                                                                                          |
+| `acceptance[]`     | Критерии приёмки (1–30)                                                                                                                                                                                                  |
+| `role`             | Роль из политики                                                                                                                                                                                                         |
+| `repositoryId`     | Репозиторий из политики; `relatedRepositories[]` — поручение уровня workspace (минимум два)                                                                                                                              |
+| `writeScope[]`     | Область записи: относительные пути без glob, `.`/`..`; пересекается с областью роли; `["."]` — весь репозиторий (только как единственный элемент; защищённые, генерируемые пути и область роли по-прежнему ограничивают) |
+| `dependsOn[]`      | Поручения графа или подтверждённые предпосылки                                                                                                                                                                           |
+| `gates[]`          | Область доказательства: gates и группы `@имя`, замкнута по `dependsOn`, содержит test gate; нет поля — все gates                                                                                                         |
+| `consumers[]`      | Потребители (зависят от репозитория поручения) и их gates                                                                                                                                                                |
+| `properties[]`     | Свойства договора проверки, подтверждаемые сейчас                                                                                                                                                                        |
+| `resources[]`      | Ресурсы политики                                                                                                                                                                                                         |
+| `requirements[]`   | Требование: текст, его SHA-256, test gate из области, testcase                                                                                                                                                           |
+| `contracts[]`      | `{id, digest}` закреплённых контрактов                                                                                                                                                                                   |
+| `context[]`        | ID обязательных источников контекста                                                                                                                                                                                     |
+
+### WorkGraph
+
+`{apiVersion, id, source, orders[], prerequisites[]}` — неизменяемый снимок
+состава и зависимостей одного согласования; `workGraphDigest` закрепляет
+согласование. Предпосылка — `{id, repositoryId, resultSha, receipt}`,
+`receipt` — `{kind: 'engine', runId}` или `{kind: 'trusted', issuer, digest}`.
+Доверие к `trusted` решает `WorkSource.trusts`: `Harness.run({ source })`
+спрашивает источник графа (его `id` обязан совпасть с `graph.source.connector`);
+без источника доверенных receipt нет. В обоих случаях движок проверяет, что
+result SHA доступен в target ref.
+
+### ExecutionPolicy
+
+| Поле                                                         | Смысл                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `policyVersion`, `mode`                                      | `1`; `live` или `fixture` (runtime `fixture` только в нём)                                                                                                                                                                                                                           |
+| `repositories[]`                                             | ID, путь, `targetRef` по правилам `git check-ref-format`, `dependsOn`, gates (`test` с обязательным JUnit внутри worktree, `check`), группы gates (≤100), защищённые и генерируемые пути, среда, lifecycle, шаги подготовки, сборки зависимостей и preflight                         |
+| `workspaceGates[]`, `verificationMode`, `workspaceLifecycle` | Gates совместной проверки комбинации репозиториев; `all` или `affected`; окружение совместной проверки                                                                                                                                                                               |
+| `roles{}`                                                    | `writer`, `writePaths`, своё правило `review` кода, `requiresContract`                                                                                                                                                                                                               |
+| `review.code / plan / contract`                              | `{reviewer, vendor}`; reviewer задан явно                                                                                                                                                                                                                                            |
+| `approvalMode`                                               | `agent` или `operator` для технического согласования                                                                                                                                                                                                                                 |
+| `isolation`                                                  | `{mode: 'os' \| 'none', domains[]}`, по умолчанию `os`                                                                                                                                                                                                                               |
+| `toolProfiles{}`, `environment`, `lifecycle`, `resources[]`  | Инструменты (у профиля — встроенные инструменты claude, shell и сеть codex, MCP-серверы `mcp{}`: stdio-команда или http-адрес, только перечисленные `tools`, учётные данные — именами переменных `env`/`bearerTokenEnv`, передаются CLI по имени), среда, ресурсы (порты 1024–65535) |
+| `concurrency`, `leaseMs`, `runTimeoutMs`, `reviewProbes`     | Пределы исполнения                                                                                                                                                                                                                                                                   |
+| `maxAttempts`, `repairBudget`, `reuseImplementation`         | Повторы и повторное использование кандидата                                                                                                                                                                                                                                          |
+| `reviewProtocolRetries`                                      | Необязательное: дополнительные вызовы reviewer кода при ошибке протокола ответа (0–2; нет поля — 1, умолчание не подставляется и digest политики не меняет), [review-protocol.md](review-protocol.md)                                                                                |
+| `budgets{work, group, total, onUnknown}`, `prices[]`         | Пределы USD и/или времени; тарифы                                                                                                                                                                                                                                                    |
+
+Переменные `HARNESS_*` и `DEVCONTOUR_*` политика задать не может.
+
+`policyDigest(policy)` — digest загруженной политики целиком: им сверяются
+применённая политика (`control.appliedPolicy`) и запрос операции
+`control.reconfigure`. `executionDigest(policy)` — digest исполнительной
+части без `budgets` и `prices`: основание согласования графа
+(`GraphState.policyDigest`) и fencing попыток (`AttemptState.policyDigest`
+у standalone-хоста). Поднятый предел бюджета поэтому согласования не
+сбрасывает.
+
+Хост, который строит политику из собственной конфигурации, может передать
+движку своё тождество применённой политики (`EngineOptions.policyIdentity`,
+digest по формуле хоста — например, файла конфигурации). Тогда применённая
+политика и запрос операции сверяются с ним, а не с `policyDigest(policy)`;
+изменение политики в памяти после создания движка по-прежнему проверяется по
+её содержимому.
+
+`EngineOptions.recordPolicyOnLead: false` — хост сам записывает применённую
+политику при запуске своего планировщика; получение роли controller (в том
+числе для прямой выдачи попытки) её тогда не записывает.
+
+Автор (`--author`): `codex`, `claude`, `fixture` или `external` — человек или
+инструмент вне harness; вендор `external` не совпадает ни с одним runtime.
+
+**Выбор reviewer** — только `selectReviewer(policy, kind, writer, role)`:
+`different-vendor` (умолчание) отклоняет reviewer того же вендора
+(`REVIEWER_SAME_VENDOR`), `same-vendor-allowed` разрешает его. Неявного
+«противоположного runtime» нет. Проверка входов отклоняет такую политику
+целиком; хост, ведущий движок без неё, получает блокер
+`REVIEWER_SAME_VENDOR` только у поручений этой роли — остальная очередь
+выдаётся.
+
+Правило может перечислить запасных reviewer (`alternates`, по порядку):
+берётся первый из `[reviewer, ...alternates]`, допустимый правилом вендора
+для этого автора. Так хост явно задаёт «reviewer другого вендора, чем
+автор», не полагаясь на неявный выбор. Запасные reviewer проверяются
+`policyIssues` так же, как основной.
+
+**Раунд технического ревью** плана или контракта — `technicalReview(engine,
+policy, adapters, input)`: та же реализация, что у `Harness.review`. Хост
+передаёт предмет (ID, digest, автор), свои разделы запроса, рабочий каталог
+reviewer и учёт вызова; harness выбирает reviewer, вызывает его под
+бюджетом, требует состояние каждой прежней открытой находки и записывает
+`ReviewRecord`. Предел раундов (`maxRounds`) задаёт вызывающий:
+`Harness.review` — `2 × maxAttempts`.
+Хост, который вёл раунды предмета до harness и хранит их сам, передаёт их
+как `history: {rounds, findings[]}`: пока у предмета нет раундов в движке,
+первый раунд получает номер `rounds + 1`, а находки последнего прежнего
+раунда — прежние открытые находки, состояние которых reviewer обязан назвать.
+Это только история: прежним раундам не приписываются digest, назначение
+reviewer или одобрение. Дальше нумерация идёт подряд от первого раунда
+движка, и `history` больше не учитывается.
+
+### ContextSnapshot
+
+`{apiVersion, sources[], missing[]}`. Источник —
+`{id, kind, version, repositoryId?, revision?, required, files[], references[], digest, hostDigest?}`;
+файл — `{path, digest, bytes, content: {encoding: 'utf8' | 'base64', data}}`.
+Содержимое передаётся в снимке: источник может не быть Git, и движок обязан
+получить ровно те байты, на которые выдан digest. `contextIssues` сверяет
+SHA-256 и размер каждого файла и `sourceDigest` источника; `pinnedBytes`
+отдаёт байты только после проверки. Пределы: 2 МиБ на файл, 16 МиБ на снимок.
+Снимок попытки сохраняется по digest (`context-snapshots`) и используется
+после рестарта без повторного чтения источника.
+
+### ContractDocument
+
+`{apiVersion, id, repositoryId?, title, content, artifacts?, checks?}` — вход
+`review-contract`. `artifacts` — закреплённые файлы контракта (`{path, blob}`,
+Git blob в репозитории `repositoryId`); `checks` — договор проверки
+(`checkDeclarationSchema`, `version: 1`): gate, обязательства по property ID
+(требования, тип обещания, область входов, правила ответа, способ проверки и
+его файлы, семейства и минимальные выборки, корпус) и политика расширения
+корпуса. Прошедший ревью документ хранится по digest (`contract-documents`):
+из него движок строит манифест генеративного gate поручения.
+
+## Модель исполнения
+
+Схемы в `execution.ts` — то, что `ExecutionStore` хранит транзакционно:
+
+| Запись            | Содержание                                                                                                                                                                                                                                                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GraphState`      | Граф, его digest, digest политики, техническое согласование (с `approval.context` — снимок контекста, который видел reviewer плана; только он исполняется и принимается)                                                                                                                      |
+| `WorkState`       | Закреплённое поручение, статус, попытки, результат, класс отказа, согласованные digests, удержание, блок бюджета, версия корпуса, эпизод восстановления по свойству                                                                                                                           |
+| `AttemptState`    | Владение (`token`, `owner`, `leaseUntil`), runtime и reviewer, фаза, SHA, evidence, раскрытые gates, потребители и что у них проверено, версия проверок, контекст, зависимости и свежесть, основание и источник reuse, черновик, выбор из очереди, замеры, `engineVersion`, `consumerVersion` |
+| `EvidenceRecord`  | Фаза, SHA, gate, исход, команда, лог, digest, testcases, отчёт свойств, осмотр ревью, версия проверок                                                                                                                                                                                         |
+| `ControlState`    | Пауза и её причина, классы отказов, ожидания, применённая политика, reconfigure                                                                                                                                                                                                               |
+| `ControllerLease` | Единственный действующий controller; `engineVersion` (с 0.1.0-alpha.2) — версия движка процесса: роль другой версии или без версии не перенимается, пока она жива                                                                                                                             |
+| `CallRecord`      | Вызов модели: стадия, runtime, сообщённая модель, версия, исход, процесс, монотонное время, закреплённая атрибуция (`workId`, `groupId`, `workIds`), вид предмета (`subjectKind`: поручение, группа, прочее), счётчики, стоимость и её источник                                               |
+| `ReviewRecord`    | Раунд ревью плана/контракта: предмет, digest, номер раунда, вердикт, назначение reviewer, digest закреплённого контекста плана, все находки предмета со статусами `open/closed/withdrawn`                                                                                                     |
+
+Локальные записи адресуются `(namespace, owner, key)`; пространства и их
+схемы — `localSchemas` (`usage`, `context-snapshots`, `run-keys`, `delivery`,
+`reviews`, `check-suites` — корпус подтверждённых случаев, `workflow-jobs` —
+техническая очередь ведущего, `contract-documents` — документы контрактов,
+прошедшие ревью, по digest, `spikes` — эксперименты выполнимости
+репозитория, `reproductions` — реестр воспроизведений из находок ревью по
+поручениям). `owner` — репозиторий или `@workspace`.
+
+## Ответы исполнителей
+
+Runtime возвращает сырой ответ; движок разбирает его
+`implementationResultSchema` и `reviewResultSchema`. Ответ вне схемы — отказ,
+а не самооценка writer. Reviewer называет состояние каждой прежней открытой
+находки (`previous[]`); `reviewIssues` отклоняет `approved` при блокирующей
+находке, в том числе прежней открытой, неназванную прежнюю находку и ссылку на
+неизвестную. Идентичность находки плана/контракта — `findingId(subject, {rule, message})`;
+невалидный ответ раунд не применяет (переходы и новые находки не записываются).
+
+Ревью кода ведёт историю находок поручения с ID, выданными controller
+(`codeReviewHistory`, `checkCodeReview`): reviewer называет ровно один переход
+каждой открытой находки, ошибка протокола (`REVIEW_PROTOCOL_INVALID`,
+причина и путь поля, например `previous[0].id`) отделена от содержательного
+отказа (`REVIEW_REJECTED`) и даёт ограниченный повтор только reviewer
+(`reviewProtocolRetries`, 0–2, по умолчанию 1). Evidence ревью несёт
+аддитивное поле `reviewRound`, находки — `id`/`status`, ссылки результата —
+`review`. Правила — [docs/review-protocol.md](review-protocol.md).
+
+## Выходы
+
+### RunResult
+
+Варианты по `outcome`:
+
+- `accepted` — `shas{base, candidate, integration, result}` все обязательны
+  (result = integration; он уже в target ref);
+- `rejected | blocked | cancelled | stopped` — `stopReason{code, message}` с
+  кодом из договора ошибок; result SHA нет.
+
+Общие поля: `workOrderId`, `graphId`, `source`, `runId`, `attempt`,
+`repositoryId`, `targetRef`, `inputs` (версии harness и потребителя, версия
+состояния, digests поручения, графа, политики, контекста, версия проверок),
+`checked` (снимки зависимостей, их свежесть, проверенная комбинация каждого
+потребителя), `evidence[]`, `findings[]`, `limitations[]`, `finishedAt`.
+Свежесть записывается, а не запрещает приёмку. Необязательные поля
+доказательства: `inputs.corpus` (закреплённая версия корпуса),
+`inputs.requiredGates` (раскрытые при выдаче gates), `inputs.writer` (writer
+попытки), у ссылки на evidence —
+`checks` (версия проверок записи), `property{level, manifest}` (уровень и
+манифест генеративного gate), `tests[]`/`testsTruncated` (выполненные тесты
+собственной проверки интеграции — доказательство названного testcase).
+Получатель проверяет результат `resultProblems(result, context)` /
+`assertResult`. Всё, что результат утверждает о поручении, области, входах и
+ревью, сверяется с тем, что получатель знает сам, а не с другими полями того
+же результата: согласованная сама с собой подделка иначе проходила бы.
+
+**Контекст получателя** (`ReceiverContext`):
+
+- `order` — постановка поручения у получателя; `graphId` — граф, в котором
+  он её держит; `contracts` — документы договоров поручения;
+- `policy` — политика получателя (`repositories`, `roles`, `review`): по ней
+  раскрываются область поручения и потребителей, замыкания зависимостей,
+  target ref, writer роли и назначенный reviewer с правилом вендора;
+- `contextDigest` — снимок контекста, закреплённый согласованием графа
+  (`null` — без контекста);
+- `suite`, `checkVersion` — корпус по копии получателя и закреплённая за
+  поручением версия (`null` — без корпуса; у поручения с договором проверки
+  обязательна); `specDigest` — digest согласованной постановки (по
+  умолчанию digest поручения);
+- `unobserved` — результат прежнего формата хоста, в котором входы попытки
+  не наблюдались: `dependencies` — нет снимков собственных зависимостей и их
+  свежести, `consumers` — нет свежести потребителей. Такие пустые списки не
+  сверяются с замыканием (их нет, и проверке они не подлежат); непустые
+  списки, снимки зависимостей потребителя и провайдер сверяются как обычно.
+  Какой результат имеет прежний формат, решает хост по своим правилам формата.
+- `assignment` — чем подтверждено ревью: `current` (по умолчанию) — writer и
+  reviewer назначены текущей политикой получателя; `recorded` — результат
+  несёт своё назначение, и хост перепроверяет его позже, когда назначение
+  ролей могло смениться: writer и reviewer — записанные, оба должны быть
+  runtime политики получателя, правило вендора роли соблюдено.
+
+Чего нет в контексте (репозиторий, потребитель, зависимость или роль не
+описаны в политике получателя), — отказ, а не PASS. Результат прежнего
+формата (без версии проверок, области и writer) читается на прежнем уровне
+только у поручения без договора проверки.
+
+**Модель доверия** — категория каждого поля принятого результата
+(`receiptTrust` в `src/verification/acceptance.ts`):
+
+- _ожидание получателя_ — сверяется с ожиданием, вычисленным из контекста;
+- _согласованность_ — сверяется с другими полями результата (SHA фаз,
+  свежесть со снимками, уникальность записей);
+- _сведение_ — ничего не доказывает, вердикт на него не опирается;
+- _схема_ — значение фиксировано схемой.
+
+Подлинность SHA, деревьев, artifacts и записей (их наличие в Git и в
+хранилище исполнителя) получатель не удостоверяет — это транспорт хоста.
+Таблица — проверяемое утверждение: <!-- repo-only -->`tests/receipt-trust.test.ts`<!-- /repo-only --> по JSON
+Schema строит подделку каждого поля (другое значение, удаление
+необязательного поля, пустой массив, повтор и удаление элемента) на двух
+фикстурах и требует отказа для первых двух категорий и того же вердикта для
+сведений; тест сверяет и эту таблицу с кодом.
+
+| Поле                                                    | Категория           | Правило                                                                                               |
+| ------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `apiVersion`                                            | схема               | литерал версии API                                                                                    |
+| `outcome`                                               | ожидание получателя | только accepted подтверждает приёмку                                                                  |
+| `workOrderId`                                           | ожидание получателя | ID поручения получателя                                                                               |
+| `graphId`                                               | ожидание получателя | граф поручения у получателя                                                                           |
+| `source.connector`                                      | ожидание получателя | источник поручения получателя                                                                         |
+| `source.ref`                                            | ожидание получателя | источник поручения получателя                                                                         |
+| `source.revision`                                       | ожидание получателя | редакция поручения получателя                                                                         |
+| `runId`                                                 | сведение            | идентификатор попытки у исполнителя                                                                   |
+| `attempt`                                               | сведение            | номер попытки у исполнителя                                                                           |
+| `repositoryId`                                          | ожидание получателя | репозиторий поручения                                                                                 |
+| `targetRef`                                             | ожидание получателя | target ref репозитория в политике получателя                                                          |
+| `inputs.harnessVersion`                                 | сведение            | версия исполнителя                                                                                    |
+| `inputs.consumerVersion`                                | сведение            | версия хоста исполнителя                                                                              |
+| `inputs.stateVersion`                                   | схема               | литерал версии состояния                                                                              |
+| `inputs.workOrderDigest`                                | ожидание получателя | digest поручения получателя                                                                           |
+| `inputs.graphDigest`                                    | сведение            | граф мог получить новую редакцию при неизменном поручении; привязка — digest поручения и его источник |
+| `inputs.policyDigest`                                   | согласованность     | входит в вычисление версии проверок                                                                   |
+| `inputs.contextDigest`                                  | ожидание получателя | снимок контекста согласования у получателя                                                            |
+| `inputs.checks`                                         | ожидание получателя | версия проверок, вычисленная получателем                                                              |
+| `inputs.corpus.suite`                                   | ожидание получателя | корпус, закреплённый за поручением у получателя                                                       |
+| `inputs.corpus.number`                                  | ожидание получателя | номер этой версии в корпусе получателя                                                                |
+| `inputs.corpus.digest`                                  | ожидание получателя | версия корпуса, закреплённая у получателя                                                             |
+| `inputs.corpus`                                         | ожидание получателя | привязка к корпусу, закреплённому у получателя                                                        |
+| `inputs.requiredGates`                                  | ожидание получателя | область поручения, раскрытая по политике получателя; без поля — область получателя                    |
+| `inputs.requiredGates[]`                                | ожидание получателя | ровно эта область, без повторов                                                                       |
+| `inputs.writer`                                         | ожидание получателя | writer роли поручения; без поля — writer роли получателя                                              |
+| `inputs.writer.runtime`                                 | ожидание получателя | writer роли поручения в политике получателя                                                           |
+| `inputs.writer.model`                                   | сведение            | модель writer                                                                                         |
+| `checked.dependencies`                                  | ожидание получателя | замыкание зависимостей репозитория по политике получателя                                             |
+| `checked.dependencies[]`                                | ожидание получателя | ровно один снимок каждой зависимости замыкания                                                        |
+| `checked.dependencies[].repositoryId`                   | ожидание получателя | зависимость из замыкания                                                                              |
+| `checked.dependencies[].sha`                            | согласованность     | совпадает со снимком в свежести                                                                       |
+| `checked.dependencies[].tree`                           | сведение            | подлинность дерева — Git хоста                                                                        |
+| `checked.dependencies[].artifacts`                      | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.dependencies[].artifacts[]`                    | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.dependencies[].artifacts[].path`               | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.dependencies[].artifacts[].digest`             | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.freshness`                                     | ожидание получателя | свежесть каждой зависимости замыкания                                                                 |
+| `checked.freshness[]`                                   | ожидание получателя | ровно одна запись на зависимость                                                                      |
+| `checked.freshness[].repositoryId`                      | ожидание получателя | зависимость из замыкания                                                                              |
+| `checked.freshness[].snapshot`                          | согласованность     | совпадает со снимком зависимости                                                                      |
+| `checked.freshness[].head`                              | согласованность     | fresh ⇔ head = snapshot; значение головы — наблюдение                                                 |
+| `checked.freshness[].fresh`                             | согласованность     | fresh ⇔ head = snapshot                                                                               |
+| `checked.consumers`                                     | ожидание получателя | объявленные потребители поручения                                                                     |
+| `checked.consumers[]`                                   | ожидание получателя | ровно одно описание каждого объявленного потребителя                                                  |
+| `checked.consumers[].repositoryId`                      | ожидание получателя | объявленный потребитель                                                                               |
+| `checked.consumers[].gates`                             | ожидание получателя | область потребителя, раскрытая по политике получателя                                                 |
+| `checked.consumers[].gates[]`                           | ожидание получателя | ровно эта область, без повторов                                                                       |
+| `checked.consumers[].sha`                               | согласованность     | совпадает со снимком потребителя в его свежести                                                       |
+| `checked.consumers[].tree`                              | сведение            | подлинность дерева — Git хоста                                                                        |
+| `checked.consumers[].dependencies`                      | ожидание получателя | замыкание зависимостей потребителя по политике получателя                                             |
+| `checked.consumers[].dependencies[]`                    | ожидание получателя | ровно один снимок каждой зависимости замыкания                                                        |
+| `checked.consumers[].dependencies[].repositoryId`       | ожидание получателя | зависимость из замыкания                                                                              |
+| `checked.consumers[].dependencies[].sha`                | согласованность     | у провайдера — result SHA; у прочих — снимок в свежести                                               |
+| `checked.consumers[].dependencies[].tree`               | сведение            | подлинность дерева — Git хоста                                                                        |
+| `checked.consumers[].dependencies[].artifacts`          | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.consumers[].dependencies[].artifacts[]`        | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.consumers[].dependencies[].artifacts[].path`   | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.consumers[].dependencies[].artifacts[].digest` | сведение            | подлинность artifacts — Git хоста                                                                     |
+| `checked.consumers[].freshness`                         | ожидание получателя | свежесть каждого входа потребителя, кроме провайдера, и его самого                                    |
+| `checked.consumers[].freshness[]`                       | ожидание получателя | ровно одна запись на вход                                                                             |
+| `checked.consumers[].freshness[].repositoryId`          | ожидание получателя | вход потребителя                                                                                      |
+| `checked.consumers[].freshness[].snapshot`              | согласованность     | совпадает со снимком входа                                                                            |
+| `checked.consumers[].freshness[].head`                  | согласованность     | fresh ⇔ head = snapshot; значение головы — наблюдение                                                 |
+| `checked.consumers[].freshness[].fresh`                 | согласованность     | fresh ⇔ head = snapshot                                                                               |
+| `evidence`                                              | ожидание получателя | решающие записи всех обязательных проверок обеих фаз                                                  |
+| `evidence[]`                                            | согласованность     | записи уникальны по ID                                                                                |
+| `evidence[].id`                                         | согласованность     | уникален                                                                                              |
+| `evidence[].kind`                                       | согласованность     | согласован с gate (ревью ⇔ independent-review) и с потребителем                                       |
+| `evidence[].phase`                                      | согласованность     | SHA записи — SHA её фазы                                                                              |
+| `evidence[].gate`                                       | ожидание получателя | обязательная проверка поручения, потребителя или ревью                                                |
+| `evidence[].sha`                                        | согласованность     | SHA фазы: candidate или result                                                                        |
+| `evidence[].passed`                                     | ожидание получателя | решающая запись каждой обязательной проверки — PASS                                                   |
+| `evidence[].digest`                                     | сведение            | подлинность записи — хранилище исполнителя                                                            |
+| `evidence[].summary`                                    | сведение            | описание записи                                                                                       |
+| `evidence[].consumer`                                   | ожидание получателя | объявленный потребитель                                                                               |
+| `evidence[].checks`                                     | ожидание получателя | версия проверок, вычисленная получателем, у каждой записи                                             |
+| `evidence[].tests`                                      | ожидание получателя | доказательство названного testcase решающей записью                                                   |
+| `evidence[].tests[]`                                    | ожидание получателя | элемент названного testcase; прочие элементы — сведения                                               |
+| `evidence[].tests[].id`                                 | ожидание получателя | ID названного testcase                                                                                |
+| `evidence[].tests[].status`                             | ожидание получателя | названный testcase прошёл                                                                             |
+| `evidence[].tests[].opaque`                             | ожидание получателя | имя названного testcase не скрыто                                                                     |
+| `evidence[].testsTruncated`                             | ожидание получателя | список решающей записи полон                                                                          |
+| `evidence[].property`                                   | ожидание получателя | доказательство договора проверки; у записи потребителя — только legacy без манифеста                  |
+| `evidence[].property.level`                             | ожидание получателя | уровень manifest; у записи потребителя — legacy                                                       |
+| `evidence[].property.manifest`                          | ожидание получателя | манифест договора поручения                                                                           |
+| `evidence[].property.manifest.digest`                   | ожидание получателя | манифест, вычисленный получателем                                                                     |
+| `evidence[].property.manifest.properties`               | ожидание получателя | свойства поручения                                                                                    |
+| `evidence[].property.manifest.properties[]`             | ожидание получателя | свойства поручения                                                                                    |
+| `evidence[].property.manifest.corpus`                   | ожидание получателя | корпус закреплённой версии                                                                            |
+| `evidence[].property.manifest.corpus.digest`            | ожидание получателя | версия корпуса у получателя                                                                           |
+| `evidence[].property.manifest.corpus.cases`             | ожидание получателя | число случаев этой версии                                                                             |
+| `evidence[].reviewer`                                   | ожидание получателя | reviewer, назначенный политикой получателя                                                            |
+| `evidence[].reviewer.runtime`                           | ожидание получателя | reviewer роли в политике получателя                                                                   |
+| `evidence[].reviewer.model`                             | сведение            | модель reviewer                                                                                       |
+| `evidence[].reviewer.sameVendor`                        | согласованность     | вендоры writer и reviewer                                                                             |
+| `evidence[].review`                                     | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.round`                               | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.call`                                | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.protocol`                            | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.issues`                              | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.issues[]`                            | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.issues[].path`                       | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.issues[].reason`                     | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.issues[].message`                    | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.transitions`                         | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.transitions[]`                       | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.transitions[].id`                    | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.transitions[].from`                  | сведение            | раунд протокола ревью кода                                                                            |
+| `evidence[].review.transitions[].to`                    | сведение            | раунд протокола ревью кода                                                                            |
+| `findings`                                              | сведение            | сводка находок может относиться к отклонённым раундам                                                 |
+| `findings[]`                                            | сведение            | сводка находок                                                                                        |
+| `findings[].severity`                                   | сведение            | сводка находок                                                                                        |
+| `findings[].message`                                    | сведение            | сводка находок                                                                                        |
+| `findings[].path`                                       | сведение            | сводка находок                                                                                        |
+| `findings[].line`                                       | сведение            | сводка находок                                                                                        |
+| `findings[].rule`                                       | сведение            | сводка находок                                                                                        |
+| `findings[].id`                                         | сведение            | сводка находок                                                                                        |
+| `findings[].status`                                     | сведение            | сводка находок                                                                                        |
+| `limitations`                                           | сведение            | чего результат не доказывает                                                                          |
+| `limitations[]`                                         | сведение            | чего результат не доказывает                                                                          |
+| `finishedAt`                                            | сведение            | время окончания                                                                                       |
+| `shas.base`                                             | сведение            | база кандидата; подлинность — Git хоста                                                               |
+| `shas.candidate`                                        | согласованность     | SHA решающих записей кандидата                                                                        |
+| `shas.integration`                                      | согласованность     | равен result SHA                                                                                      |
+| `shas.result`                                           | согласованность     | SHA решающих записей интеграции и снимка провайдера у потребителей                                    |
+
+### DeliveryState и ResultEnvelope
+
+Доставка — отдельно от исхода: `{sink, key, revision, status: pending |
+delivered | failed | conflict, attempts, lastError?, currentRevision?,
+receipt?, updatedAt}`. `harness result` выдаёт `{apiVersion, result,
+delivery[]}`.
+
+### JointVerification
+
+Совместная проверка закреплённой комбинации SHA нескольких репозиториев:
+`{id, status, policyDigest, specDigest, workIds[], manifest{repo: {sha, tree}},
+manifestDigest, impact?, evidence[], error?}`. Смена любого SHA делает
+результат устаревшим; атомарность продвижения нескольких репозиториев не
+заявляется. Продуктовое принятие комбинации решает хост. Пока manifest не
+закреплён, `impact` может нести только ссылку на базовую проверку
+(`baseline`), выбранную хостом для режима `affected`.
+
+### RunEvent
+
+`{apiVersion, seq, at, type, graphId?, workId?, runId?, attempt?, payload}`.
+`seq` строго возрастает. Нагрузка каждого из типов (`eventPayloads`) — закрытая
+схема: лишних полей нет, поэтому токен владения, секрет или объект попытки в
+событие не попадает.
+
+`transactionKinds` — имена транзакций исполнения; совпадают с сохранёнными
+типами событий журнала хоста (`run.claimed`, `task.done`, `run.failed`,
+`scheduler.error`, …). `workflow.updated` пишет только локальные записи
+технической очереди (`workflow-jobs`) и событий журнала не создаёт.
+`usage.recorded` пишет только локальные записи учёта вызовов (`usage`): начало
+вызова вместе с проверкой бюджетов, ход и итог вызова, закрытие прерванных,
+закрепление атрибуции прежних записей; событий журнала не создаёт.
+`checks.recorded` пишет только локальные записи корпуса (`check-suites`):
+начало, продление и завершение операции подтверждения, решение и новую
+версию. `checks.spike` пишет только локальную запись эксперимента
+выполнимости (`spikes`). `checks.adopted`, `checks.awaiting-operator` и
+`checks.adoption-abandoned` меняют принятую поручением версию корпуса и
+удержание выдачи (`work.held`, `corpus.adopted`). Эпизод по свойству меняется
+транзакциями `recovery.*`, отказом и выдачей (`work.recovery`).
+`workspace.verification.started`, `workspace.manifest`, `workspace.evidence`,
+`workspace.verified`, `workspace.failed` — транзакции совместной проверки
+(`joint.started`, `joint.finished`). `config.started`, `config.reconfigure-*`
+и `config.reconfigured` меняют применённую политику и запрос операции
+(`policy.applied`, `policy.reconfigure`). `base.moved` — проверка владения
+операцией и CAS-сдвиг ref базы; записей и событий не создаёт.
+
+## Порты
+
+| Порт                                                           | Договор                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ExecutionStore`                                               | `transact(kind, fn)`: синхронная сериализуемая транзакция; исключение откатывает изменения и события; вложенная видит несохранённые изменения внешней, её исключение откатывает только её часть, а изменения обеих сохраняются; событиями становятся только `emit`, возвращаемое значение в журнал не попадает; событие фиксируется и в транзакции без изменения записей модели; `heartbeat` без события; единственный внешний эффект — CAS update-ref при приёмке до фиксации                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `ExecutionView` / `ExecutionTransaction`                       | Чтение и запись записей модели, типизированных локальных записей, событий                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `BasisProvider`                                                | Digest постановки, области проверок и политики поручения; движок сравнивает, но не вычисляет основания хоста. Необязательный `checksDigest(work, policyDigest, view)` — версия проверок попытки по формуле хоста (по умолчанию `effectiveChecks` harness); `ReceiverContext.checksDigest` — та же формула у получателя. Необязательные `jointPolicyDigest(view)` и `jointSpecDigest(workIds, view, verificationId?)` — digest политики и основание совместной проверки по формуле хоста (по умолчанию формулы harness). Необязательный `episodeBasis(work, view)` — основание эпизода разбора по свойству по формуле хоста (по умолчанию `episodeBasis` harness): им подписаны прежние эпизоды и попытки хоста. Необязательный `suiteBasis(contract)` — нормативное основание корпуса договора проверки по формуле хоста (по умолчанию `suiteBasis` harness): им записано основание прежних корпусов хоста, их выбор (`CorpusStore.suiteFor`), привязка версии к поручению при новой редакции и у получателя (`ReceiverContext.suiteBasis`) |
+| `HostGuards`                                                   | `claimable`, `claimBarrier`, `current`, `beforeAccept` — дополнительные запреты хоста в той же транзакции; необязательный `busy(view)` — работы хоста (поставка, preview), которых применение новой политики дожидается так же, как попыток; необязательный `joint(verification, view, kind)` — продуктовые условия совместной проверки в каждой её записи, кроме продления срока                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `ContractApprovals` (необязательный `ExecutionHost.contracts`) | `approved({id, digest}, view)` — хост, ведущий согласование контрактов сам, подтверждает редакцию этого digest (`null`) или называет причину; без порта согласованием служит одобренный последний раунд технического ревью этого digest при текущем назначении reviewer. Записи ревью из сведений хоста не создаются                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ExecutionHost.readyAt` (необязательный)                       | `readyAt(work, view)` — когда поручение стало готово к выдаче (согласовано и дождалось зависимостей) по сведениям хоста; движок пишет его в `wait.readyAt` новой попытки в транзакции выдачи. Нет порта или `undefined` — время неизвестно и не выдумывается                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BudgetScopes`                                                 | Группа поручения, её состав, атрибуция прежних записей вызовов                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `RuntimeAdapter`                                               | `capabilities()`, `invoke(request, signal)`: сессия `fresh` для reviewer и planner (`continue` — только writer той же попытки), JSON Schema ответа, сообщённая модель и версия runtime, usage, диагностика, отмена дерева процессов; необязательный `probe` — сервер проверок reviewer кода (команда, имена переменных окружения, предел команды), адаптер подключает его как MCP-сервер `devcontour_probe`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `WorkSource`                                                   | `fetch(ref)` с редакцией; `revision(ref)`; `trusts(prerequisite)`, по умолчанию нет                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `ContextSource`                                                | `snapshot(ids, at)` — `ContextSnapshot` с содержимым                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ResultSink`                                                   | `deliver({key, result})` идемпотентно по ключу: `delivered` или `conflict` с текущей редакцией                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+
+`RuntimeRequest.subject` (необязательно) — поручение, попытка и фаза вызова
+исполнения: адаптер хоста находит по нему свои сведения; в запросе модели их нет.
+
+`Runner` принимает от хоста: `context(work)` — снимок контекста, в том числе
+асинхронно; `stateDirFor(repositoryId)` — каталог рабочих деревьев,
+артефактов и снимков попыток репозитория (без него — `stateDir`);
+`hooks` — точки расширения, которые добавляют сведения хоста, но не решают
+приёмку: `prepared({work, attempt, baseSha})` — база известна, работа не
+начата (отказ — отказ попытки, `BlockedError` — отказ окружения);
+`notes({work, attempt, review})` — дополнения запроса writer или reviewer;
+`implemented({attempt, output, sha})` — отчёт writer закоммичен кандидатом;
+`failed({attempt, kind, message})` — отказ записан движком. `settled()` ждёт
+выданные попытки — хост ведёт свой цикл поверх `tick`. `Engine.expire(at)`
+снимает владение, истекающее к моменту `at`. Попытка записывает замеры стадий
+(`implementation`, `<фаза>-test:<gate>`, `<фаза>-consumer:<репозиторий>:<gate>`,
+`<фаза>-review`, `<фаза>-environment:<шаг>`, `integration-wait`) и сохраняет
+снимок контекста артефактом `implementation/context.json`. Отказ приёмки с
+кодом `GATE_FAILED`, `REVIEW_REJECTED`, `REVIEW_PROTOCOL_INVALID`,
+`SCOPE_VIOLATION` или `BUDGET_EXHAUSTED` записывается классом отказа этого
+правила.
+
+Хост, ведущий движок поверх своего хранилища, собирает исполнение из
+экспортов корня пакета: `Engine`, `Runner`, `WorkflowQueue`, `JointRunner`,
+`moveBase`/`fencedRefMove`, `runGate`/`runCheck` (и разбор отчёта
+`junitSummary`, `prepareReportPath`, `sandboxBlockedHosts`), `unprovenReason`,
+`ReviewProbes`, маскирование (`redactor`, `redactDeep`, `redactError`),
+корпус (`CorpusStore`, подтверждение случая `submitCase` с `ConfirmContext`),
+ограниченный разбор по свойству (`analyzeRecovery`, `applyCases`,
+`recoveryBrief`; назначение хоста — модель и профиль ведущего — передаётся
+`binding`, его дополнительные границы — `boundary`), проверка
+переносимого результата (`resultProblems`), классы и правила отказов
+(`BlockedError`, `TaskFailure`, `classifyFailure`, `failureFingerprint`,
+`repairPolicy`, `repairDecision`), раунд технического ревью
+(`technicalReview`), точка сбоя подтверждения корпуса для тестов
+(`caseHooks`). Глубокие импорты `lib/...` не поддерживаются.
+
+Очередь технических заданий хоста — `new WorkflowQueue(store, policy, now,
+subjects)`: `subjects.input(kind, id, view)` задаёт digest входа и владельца
+задания для предметов хоста (доска, набор изменений); задание хранится за
+этим владельцем, недопустимый вход (`HarnessError`) отклоняет постановку его
+текстом и делает поставленное задание устаревшим, смена владельца — тоже.
+Число стадий задаёт `finish(job, wait, stages)`.
+
+## Ошибки и exit codes
+
+`HarnessError {code, class, message, issues[{path, message}]}`; класс задаёт
+exit code CLI.
+
+| Exit | Класс            | Коды                                                                                                                                                                                                                                                           |
+| ---- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | успех            | —                                                                                                                                                                                                                                                              |
+| 2    | `input`          | `INVALID_INPUT`, `UNSUPPORTED_COMMAND`, `UNSUPPORTED_VERSION`, `GRAPH_*`, `GATE_*`, `REVIEWER_*`                                                                                                                                                               |
+| 3    | `refused`        | `APPROVAL_STALE`, `APPROVAL_REQUIRED`, `LEASE_STALE`, `CONTROLLER_BUSY`, `PAUSED`, `NOT_READY`, `SCOPE_VIOLATION`, `GATE_FAILED`, `REVIEW_REJECTED`, `BUDGET_EXHAUSTED`, `BUDGET_UNKNOWN`, `ATTEMPTS_EXHAUSTED`, `REVISION_CONFLICT`, `CANCELLED`, `NOT_FOUND` |
+| 4    | `infrastructure` | `STATE_VERSION_UNSUPPORTED`, `RUNTIME_UNAVAILABLE`, `REVIEW_PROTOCOL_INVALID`, `SANDBOX_UNAVAILABLE`, `GIT_FAILED`, `STORAGE_FAILED`, `DELIVERY_FAILED`, `INTERNAL`                                                                                            |
+
+Exit 1 не используется: им Node завершает процесс при необработанном
+исключении.
+
+### StackProfile
+
+Переносимый профиль стека (`schemas/stack-profile.schema.json`):
+`{id, version, extends[], capabilities[], gates[], prepare[], environment?, lifecycle?, protectedPaths[], generatedPaths[], concurrency?, runTimeoutMs?, roles{}, contextPacks[]}`.
+`extends` — встроенный ID (`profiles/<id>.json` пакета) или относительный
+`./file.json` внутри репозитория; не глубже 16 слоёв и не больше 32 файлов,
+без symlink и выхода за корень, файл до 128 KiB. `resolveProfile` только
+читает манифесты: gates, подготовка, возможности и пути складываются,
+окружение и lifecycle задаёт один слой (иначе конфликт), параллельность —
+наименьшая, время попытки — наибольшее, роли и `contextPacks` — по ID.
+Итог обязан иметь test gate с JUnit; `requirement-source` зарезервирован.
+Файлы локальных слоёв становятся защищёнными путями. Digest: один встроенный
+файл — sha256 его байтов (так закреплены прежние потребители, встроенные
+профили перенесены побайтно), иначе — sha256 замыкания `[{ref, digest}]`.
+`repositoryFromProfile` собирает описание репозитория политики (собственные
+значения сильнее, переопределённые поля названы в `shadowed`),
+`profileRoles` — роли в форме политики. `contextPacks` — инструкции стека для
+хоста: harness их не читает, закрепляет их `ContextSource`. Встроенные
+профили сохраняют имена скриптов проекта, которые закреплены у прежних
+потребителей (например, `npm run test:devcontour`); для другого проекта
+подходит локальный профиль.
+
+## CLI
+
+stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}` или
+`{apiVersion, command, ok: false, error}`. `data` каждой команды проверяется
+её схемой (`cliDataSchemas`) перед выводом. Диагностика — stderr. Команды
+получают явные пути; `--state <каталог>` создают только пишущие команды,
+читающие на отсутствующем каталоге отвечают `NOT_FOUND` и ничего не создают.
+Бинарник не хранит настроек проекта и не помнит «последний активный проект».
+
+| Команда           | Аргументы                                                               | Пишет | `data`                                                                  | Повтор                                                                                                                                                 |
+| ----------------- | ----------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `validate`        | `--graph F --policy F [--context F]`                                    | нет   | digests, число поручений                                                | Чистая функция входов                                                                                                                                  |
+| `review-plan`     | `--state D --graph F --policy F --author A [--context F]`               | да    | `ReviewRecord`                                                          | Тот же digest и автор, уже согласованные, — тот же раунд без вызова модели; автор, не допускаемый правилом вендора, — `REVIEWER_SAME_VENDOR` до вызова |
+| `review-contract` | `--state D --contract F --policy F --author A`                          | да    | `ReviewRecord`                                                          | Как `review-plan`                                                                                                                                      |
+| `approve`         | `--state D --subject ID --digest H`                                     | да    | subject, digest, at                                                     | Тот же digest — без изменений; только `approvalMode: operator`                                                                                         |
+| `run`             | `--state D --graph F --policy F [--context F] [--sink file:D] [--once]` | да    | граф, поручения и их блокеры, задание `workflow`                        | Та же редакция продолжает работу; другой digest той же редакции — `REVISION_CONFLICT`                                                                  |
+| `status`          | `--state D [--graph ID]`                                                | нет   | очередь, графы, поручения с блокерами, бюджеты                          | Только чтение                                                                                                                                          |
+| `events`          | `--state D [--after N] [--limit 1–500]`                                 | нет   | события, `next`                                                         | Только чтение                                                                                                                                          |
+| `pause`           | `--state D`                                                             | да    | `ControlState`                                                          | Без изменений                                                                                                                                          |
+| `resume`          | `--state D`                                                             | да    | `ControlState`                                                          | Решение человека: снимает паузу оператора, штатной остановки и отказа runtime вместе с её классами; паузу операции reconfigure — `PAUSED`              |
+| `cancel`          | `--state D --work ID [--reason T]`                                      | да    | статус поручения                                                        | Отменённое — без изменений; это не retry                                                                                                               |
+| `retry`           | `--state D --work ID [--reset --reason T]`                              | да    | статус поручения                                                        | В пределах `maxAttempts` и бюджета; `--reset` с причиной сбрасывает счётчик попыток, но не учёт расходов                                               |
+| `result`          | `--state D --work ID`                                                   | нет   | `ResultEnvelope`                                                        | Только чтение                                                                                                                                          |
+| `deliver`         | `--state D --work ID --sink file:D`                                     | да    | `ResultEnvelope`                                                        | Доставленное не доставляется повторно; моделей и интеграции нет                                                                                        |
+| `profile`         | `--profile ID\|./F [--repository D]`                                    | нет   | закрепление (`pin`) и разрешённый профиль                               | Чистая функция файлов профиля; команды проекта не исполняются                                                                                          |
+| `doctor`          | `[--state D] [--policy F]`                                              | нет   | версии, runtime, sandbox, совместимость состояния и версии движка в нём | Без live-вызова модели                                                                                                                                 |
+| `--version`       | —                                                                       | нет   | версия пакета и API                                                     | —                                                                                                                                                      |
+
+Полная форма каждой команды — `cliCommands` (аргументы, обязательность,
+идемпотентность, отказы exit 3). Все команды реализованы. `run` принимает `--author` (по умолчанию `external`) — автора графа для ревью плана. `HARNESS_CODEX_BIN` и `HARNESS_CLAUDE_BIN` подменяют исполняемые файлы runtime (fixture executables в тестах).
+После приёмки договора имена и параметры меняются только совместимо или
+отдельным согласованным изменением.