devcontour-harness 0.1.0-alpha.5 → 0.1.0-alpha.6

package/README.md

@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
 интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
 и доказательствами.
 
-> Статус: `0.1.0-alpha.5` — предварительный выпуск (alpha). Договоры
+> Статус: `0.1.0-alpha.6` — предварительный выпуск (alpha). Договоры
 > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
 > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
 > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -27,7 +27,7 @@ Headless-движок исполнения инженерных поручени
 Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
 
 ```sh
-npm install --save-exact devcontour-harness@0.1.0-alpha.5   # точная версия
+npm install --save-exact devcontour-harness@0.1.0-alpha.6   # точная версия
 # или: npm install --save-exact devcontour-harness@alpha     # текущая alpha
 npx harness --version
 ```
@@ -117,6 +117,28 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
 `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
 Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
 
+## Выпуск 0.1.0-alpha.6
+
+Ядро работает как прежде; всё новое подключается явно. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.6.md).
+
+- Инструменты целевого проекта: npm, pnpm, Turborepo, Go/gotestsum,
+  Python/uv — явными шагами `prepare`, gates и `repositories[].toolchain`;
+  `doctor` и обязательный preflight `run` ([toolchains](docs/toolchains.md)).
+- Рецепт Turbo Starter с lifecycle-мостом Docker
+  ([turbo-starter](docs/turbo-starter.md)).
+- Коннектор задач с транспортами Relay v1 и Relay-2: команды `source-*`,
+  `run --source`, доставка с намерением, read-back и явным разбором
+  неизвестного исхода ([connectors](docs/connectors.md)).
+- Протокол ревью кода: ID и переходы находок, ограниченный повтор reviewer,
+  `REVIEW_PROTOCOL_INVALID` ([review-protocol](docs/review-protocol.md));
+  объявленные gates в проверках reviewer ([review-probes](docs/review-probes.md)).
+- Точка подключения внешней памяти — договор без готового адаптера
+  ([hindsight](docs/integrations/hindsight.md)).
+
+Состояние alpha.5 читается без преобразования. Standalone-состояние с новыми записями
+alpha.5 не читает; прежний DevContour его открывает без отказа — откат только через копию ([upgrade](docs/upgrade.md)).
+
 ## Выпуск 0.1.0-alpha.5
 
 Первая публикация в npm. Движок, форматы состояния, политики и договоры — те

package/docs/compatibility-versions.md

@@ -0,0 +1,56 @@
+# Проверенные версии
+
+Набор версий, на котором выпуск фактически проверен. Это не список
+обязательных требований: другие версии могут работать, но не проверялись.
+Строки с «TODO» заполняются по итогам приёмки выпуска.
+
+## Пакет и потребители
+
+| Что                    | Версия                                              | Где проверено                          |
+| ---------------------- | --------------------------------------------------- | -------------------------------------- |
+| ОС / архитектура       | macOS 15 (Darwin 24.6), arm64                       | все проверки выпуска                   |
+| Node.js                | 24.3.0 (`engines: >=24.3.0`)                        | все проверки выпуска                   |
+| npm                    | 11.4.2                                              | C01 (установка архива), A01, A02       |
+| pnpm                   | 10.12.3                                             | C01 (`pnpm add <архив> --prod`)        |
+| TypeScript потребителя | 6.0.3 + `@types/node` 24.13.5                       | A01, C01 (ставится отдельно от пакета) |
+| Прежний потребитель    | API 0.1.0-alpha.5                                   | A01                                    |
+| DevContour             | 0.4.0-alpha.7 (`e26f8f4`), vendored alpha.4 → архив | C02                                    |
+| Git                    | 2.33.0                                              | все сценарии                           |
+
+## Инструменты целевых проектов
+
+| Что            | Версия | Где проверено  |
+| -------------- | ------ | -------------- |
+| Turbo          | TODO   | T01/turbo, S01 |
+| Go / gotestsum | TODO   | T01/go         |
+| Python / uv    | TODO   | T01/python     |
+| Docker         | TODO   | S01–S06        |
+
+## Транспорты
+
+| Что                 | Версия / commit | Где проверено |
+| ------------------- | --------------- | ------------- |
+| Relay v1 (server)   | TODO            | R01, W01      |
+| Relay-2 (CLI) / Bun | TODO            | R02, R03, W01 |
+
+## Как повторить
+
+<!-- repo-only -->
+
+Проверки выпуска — инструменты разработки harness: они лежат в checkout
+репозитория (`scripts/acceptance/`, `tests/fixtures/consumer-alpha5`) и в
+npm-архив не входят.
+
+```sh
+node scripts/acceptance/package-pack.mjs --out <dir>
+node scripts/acceptance/package-check.mjs <dir>/devcontour-harness-<ver>.tgz
+node scripts/acceptance/consumer-check.mjs <dir>/devcontour-harness-<ver>.tgz
+node scripts/acceptance/core-minimal-env.mjs <dir>/devcontour-harness-<ver>.tgz
+node scripts/acceptance/devcontour-check.mjs <dir>/devcontour-harness-<ver>.tgz \
+  --devcontour <путь или URL DevContour> --baseline
+```
+
+Отчёты скриптов (`report.json`) содержат фактические версии `node`, `npm`,
+`pnpm` и компилятора, hash архива и argv каждой команды.
+
+<!-- /repo-only -->

package/docs/compatibility.md

@@ -91,7 +91,7 @@ coordinator. `Store.change(type, fn)` открывает `BEGIN IMMEDIATE` (вл
 | `WorkState`              | `Task` (поля исполнения)                                                                                        | `status`, `attempt`, `activeRunId`, `resultSha`, `failure`, `failureKind`, `failureFingerprint`, `approvedAt`, `approvedDigest`, `approvedScope`, `approval`, `hold`, `budgetBlock`, `checkVersion`, `recovery`, `recoveryHistory` — те же имена и формы. `graphId` — доска, в активной ревизии которой задача                                                                                                                                                    |
 | `WorkOrder`              | `Task` (поля постановки)                                                                                        | `description` → `goal`; `writePaths` (или область роли) → `writeScope`; `contracts` + `contractDigests` → `contracts[{id, digest}]`; `contextPacks` → `context`; `source` = `{connector: 'devcontour', ref: <taskId>, revision: <approvedDigest>}`. Продуктовые поля (`preparation`, `featureId`, `assignee`, `supersedes`, `finding`, `sharedCompletion`, `scope`) в поручение не входят и остаются в `Task`                                                     |
 | `AttemptState`           | `Run`                                                                                                           | Те же имена и формы, включая `context` (краткие pins), `consumers[].checked`, `partial`, `continuedFrom`, `dispatch`, `timings`; `taskId` ↔ `workId`; runtime `demo` ↔ `fixture` на границе (сохранённое значение не переписывается); `memory` остаётся полем `Run` хоста; `engineVersion`, `consumerVersion`, `contextSnapshot` — новые необязательные поля                                                                                                      |
-| `EvidenceRecord`         | `Evidence`                                                                                                      | Без изменений                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `EvidenceRecord`         | `Evidence`                                                                                                      | Без изменений; аддитивные необязательные `reviewRound` и `findings[].id/status` ([review-protocol.md](review-protocol.md)) хранятся как есть, прежние записи читаются без них; строгие переходы находок — только для адаптера reviewer с необязательным `RuntimeCapabilities.reviewProtocol: 1` (`cliAdapter`), runtime-обёртки хоста без поля сохраняют приёмку alpha.5                                                                                          |
 | `ControlState`           | `paused`, `pauseReason`, `pausedAt`, `pauseOperation`, `pauseFailures`, `waits`, `appliedConfig`, `reconfigure` | Те же формы; `appliedConfig` ↔ `appliedPolicy`                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `ControllerLease`        | `leader`                                                                                                        | Без изменений                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `JointVerificationState` | `Verification`                                                                                                  | `manifest`, `manifestDigest`, `policyDigest`, `specDigest`, `impact`, `evidence`, `token`, `leaseUntil`, `status` — те же формы; `tasks` → `workIds` (снимок задач остаётся в `Verification`); `boards`, `productRelease` — поля хоста                                                                                                                                                                                                                            |
@@ -181,7 +181,7 @@ Gates, шаги подготовки и проверки потребителе
 | Версия движка в основании reuse | Попытка записывает `engineVersion` (и `consumerVersion`). Кандидат попытки другой версии движка повторно не используется: новая попытка заново проходит gates и ревью. Прежние попытки сохраняют своё основание; отсутствующая версия не выдумывается                 |
 | Reviewer задаётся правилом      | `different-vendor` по умолчанию; `same-vendor-allowed` включается явно                                                                                                                                                                                                |
 | Токены вне журнала              | Исправление утечки: прежде `run.claimed` и `run.recovered` записывали в журнал попытку целиком, с fencing-токеном. Новые события пишутся без токенов; при выдаче старых событий наружу (CLI, HTTP, RunEvent) токены удаляются. Историю базы физически не переписываем |
-| История находок ревью           | Reviewer называет состояние прежних находок; прежние попытки читаются без статусов                                                                                                                                                                                    |
+| История находок ревью           | Reviewer называет состояние прежних находок; прежние попытки читаются без статусов; ревью кода ведёт историю находок поручения с ID controller, находки записей alpha.5 получают детерминированный ID (review-protocol.md)                                            |
 
 ## Состояние standalone
 

package/docs/connectors.md

@@ -0,0 +1,323 @@
+# Коннектор задач: Relay v1 и Relay-2
+
+Коннектор подключает к harness внешнее хранилище задач: читает задачу,
+закрепляет её постановку, исполняет её обычным путём (ревью плана →
+согласование → изолированная попытка → gates → независимое ревью → приёмка в
+Git) и доставляет подтверждённый результат обратно в задачу. Это opt-in
+модуль `devcontour-harness/integrations/connector`: корень пакета и
+`./contracts` его не импортируют, адаптер backend загружается только для
+явно выбранного provider.
+
+Поддерживаются два независимых транспорта:
+
+| provider        | Backend                                     | Транспорт                                                                                             |
+| --------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `relay-v1-http` | Relay v1 (`/api/v1`, project-scoped routes) | HTTP, `src/integrations/relay-v1`                                                                     |
+| `relay-v2-cli`  | Relay-2                                     | subprocess CLI (`--format json`, явные `--config`/`--project`/`--actor`), `src/integrations/relay-v2` |
+
+Provider выбирается **только явно** в конфигурации — никогда по имени
+бинарника `relay`. Базы v1 и v2 не взаимозаменяемы, миграции истории нет.
+
+## Пользовательский путь
+
+Все шаги — команды CLI; TypeScript писать не нужно.
+
+```sh
+# 1. Настроить: connector.json (см. «Конфигурация») и policy.json harness.
+
+# 2. Проверить подключение, проект, capabilities и mapping — только чтение:
+#    ни мутаций, ни записи истории, ни создания состояния.
+npx harness source-check --source connector.json --policy policy.json --state ../state
+
+# 3. Прочитать и закрепить снимок задач: graph.json, context.json, manifest.json.
+npx harness source-snapshot --source connector.json --policy policy.json --state ../state --out ../snapshot
+
+# 4. Обычное согласование (approvalMode: operator) — по файлам снимка.
+npx harness review-plan --state ../state --policy policy.json --source connector.json \
+  --graph ../snapshot/graph.json --context ../snapshot/context.json --author external
+npx harness approve --state ../state --subject <graphId> --digest <graphDigest>
+#    С --source внешние предпосылки (зависимости, выполненные через этот
+#    коннектор) допускаются по решению источника (trusts) и доступности SHA в
+#    target ref — те же правила, что у run; без --source доверенных receipt нет.
+#    В approvalMode: agent ревью плана выполняется в шаге 5 автоматически.
+
+# 5. Запуск: задачи перечитываются, semantic digest сверяется с закреплённым
+#    снимком, eligibility проверяется — всё до любого вызова runtime.
+#    Принятый результат доставляется в исходную задачу.
+npx harness run --source connector.json --policy policy.json --state ../state
+
+# 6. Локальный и внешний статус: принято / доставлено / конфликт / неизвестный
+#    исход и независимое чтение получателя.
+npx harness source-status --source connector.json --state ../state
+
+# 7. Повтор или продолжение доставки — с тем же ключом операции; writer,
+#    reviewer, gates и Git не вызываются.
+npx harness source-deliver --source connector.json --state ../state [--work <workId>]
+
+# 8. Разбор неизвестного исхода или конфликта (см. «Восстановление»).
+npx harness source-reconcile --source connector.json --state ../state \
+  --operation <key> [--decision resend|adopt:<id>|recheck]
+```
+
+`<graphId>`, `<graphDigest>`, ключи операций и ID поручений выводят
+`source-snapshot` и `source-status` (JSON в stdout). Exit codes как у всего
+CLI: 0 — успех, 2 — неверный вход, 3 — отказ/блокировка (в том числе
+`uncertain`/`conflict` доставки и непройденная проверка), 4 — инфраструктура
+(backend недоступен).
+
+## Конфигурация
+
+```json
+{
+  "version": 1,
+  "provider": "relay-v1-http",
+  "relay": { "endpoint": "http://127.0.0.1:4700" },
+  "projectId": "AbCd1234",
+  "actor": "harness-controller",
+  "repository": { "id": "app" },
+  "tasks": [
+    {
+      "ref": "PRODUCT-3",
+      "role": "developer",
+      "writeScope": ["apps/api/src", "packages/sdk/src"],
+      "gates": ["unit"],
+      "criteria": [
+        { "title": "API returns displayName", "gate": "unit", "testId": "api.user.displayName" },
+        { "id": "Ab3dE6gH", "gate": "typecheck", "evidence": "gate" }
+      ],
+      "requiredDocuments": ["Spec"]
+    }
+  ],
+  "completion": { "mode": "complete", "historicalComment": false },
+  "eligibility": { "columns": ["ready", "in-progress"] },
+  "limits": {
+    "documents": 20,
+    "documentBytes": 262144,
+    "totalBytes": 4194304,
+    "taskBytes": 1048576,
+    "rereads": 3,
+    "leaseMs": 120000
+  },
+  "history": { "enabled": true, "client": "devcontour-harness" }
+}
+```
+
+| Поле                  | Смысл                                                                                                                                                                                                                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`            | `relay-v1-http` или `relay-v2-cli`; только явно                                                                                                                                                                                                                                                                 |
+| `relay`               | Настройки адаптера. v1: `endpoint` (+ `timeoutMs`, `maxResponseBytes`). v2: `binary`, `config` (относительно файла конфигурации), `project?` (workspace), `env?` (например `RELAY_HOME`, на macOS `DYLD_LIBRARY_PATH`), `timeoutMs`, `maxOutputBytes`, `build?`. `projectId`/`actor` берутся из верхнего уровня |
+| `projectId`           | Ожидаемая идентичность проекта backend; несовпадение блокирует чтение снимка и любые мутации                                                                                                                                                                                                                    |
+| `actor`               | Автор всех записей коннектора                                                                                                                                                                                                                                                                                   |
+| `stateDir`            | Каталог состояния коннектора (относительно файла); без него — `--state`                                                                                                                                                                                                                                         |
+| `repository`          | ID репозитория политики (и путь для сверки)                                                                                                                                                                                                                                                                     |
+| `tasks[]`             | Задачи: `ref` (постоянный ID или ключ), роль, `writeScope`, `gates`, сопоставление критериев, обязательные документы                                                                                                                                                                                            |
+| `tasks[].criteria[]`  | Критерий (`id` или точный `title`) → `gate` и `testId` JUnit; `evidence: "gate"` — достаточно прошедшего gate (явный выбор)                                                                                                                                                                                     |
+| `completion`          | `complete` — закрыть по правилам backend (по умолчанию в `done`); `review-only` — перевести в `review`/`column` и оставить человеку; `historicalComment` — при конфликте постановки записать явно исторический комментарий                                                                                      |
+| `eligibility.columns` | Колонки, из которых задача допускается к запуску (`done`/`cancelled` — никогда)                                                                                                                                                                                                                                 |
+| `limits`              | Пределы документов и постановки, число повторных чтений, срок владения доставкой                                                                                                                                                                                                                                |
+| `history`             | Запись истории работы (корневая и дочерние сессии)                                                                                                                                                                                                                                                              |
+
+### Идентичность и снимок
+
+- Идентичность задачи — `<provider>:<projectId>:<постоянный ID>`; ID поручения
+  и графа — хэш от неё. Одинаковые номера задач разных проектов/backend не
+  совпадают; смена cwd на worktree идентичность не меняет.
+- `SourceRef.revision` — **semantic digest** постановки: текст, определения
+  критериев (без отметок выполнения), зависимости, подзадачи, значимые
+  документы и digest mapping. Колонка, свой in-progress, комментарии, история
+  и отметки критериев в него не входят. CAS-ревизии backend, токены
+  согласованности чтения и идентичность сборки хранятся только в manifest
+  снимка (никогда в поле Git SHA).
+- Чтение — раундами по всем задачам; снимок принимается, когда два раунда
+  подряд совпали токенами и содержимым. Изменения — не больше `rereads`
+  повторов, затем явный отказ `NOT_READY`; ошибка сети/CLI — отказ, а не
+  пустая доска.
+- Обязательное содержимое (текст постановки, критерии, `requiredDocuments`)
+  не усекается: превышение предела блокирует запуск с причиной и пределом.
+  Дополнительные документы усекаются с явной отметкой в начале файла и в
+  manifest (`truncated`) либо опускаются с записью в `missing` снимка.
+- Eligibility проверяется отдельно от digest: `done`/`cancelled`, колонка вне
+  `eligibility.columns`, незавершённая зависимость, зависимость в `done` без
+  receipt этого коннектора. Колонка, в которую задачу перевела наша
+  подтверждённая доставка той же постановки, повтор не блокирует.
+- Статус `done` зависимости — не доказательство: предпосылка зависимой
+  задачи появляется только из receipt доставки этого коннектора (издатель —
+  ID коннектора, digest сверяется с его состоянием), и движок дополнительно
+  проверяет доступность result SHA в target ref.
+
+## Доставка: протокол и гарантии
+
+Ключ операции — `sha256(provider, projectId, workId, runId, resultDigest)`.
+
+1. **Intent до вызова.** Операция записывается в состояние коннектора до
+   первого внешнего вызова. Не удалось записать — мутация не отправляется.
+2. **Сверка перед мутацией.** Задача перечитывается: изменился semantic
+   digest или задача отменена/закрыта другим — `conflict`; результат остаётся
+   привязан к своему снимку и SHA, текущая задача не закрывается (по
+   `historicalComment` — один явно исторический комментарий).
+3. **Шаги**, каждый записан до и после вызова: комментарий с маркером
+   `<!-- devcontour-harness:op=<key>:step=<n> -->`; отметки сопоставленных
+   критериев с CAS; перемещение с CAS; закрытие истории. Критерий отмечается
+   только по mapping на прошедший в integration gate/testcase принятого
+   результата; ручные критерии, непрошедший testcase, незавершённые
+   подзадачи и зависимости оставляют задачу незавершённой.
+   Перед **каждым** неподтверждённым шагом (в том числе при продолжении
+   после обрыва или перезапуска) задача перечитывается: постановка обязана
+   совпасть со снимком результата, задача — не быть отменённой или закрытой
+   другим, а для нового CAS-шага текущая ревизия — равняться ревизии,
+   записанной после **нашего** предыдущего шага. Иначе — `conflict`, и
+   изменённая задача старым результатом не закрывается.
+4. **Неизвестный исход** (таймаут, обрыв ответа, падение процесса между
+   вызовом и записью итога) разбирается фактами получателя: комментарий — по
+   маркеру (ровно один — подтверждено); CAS-шаг — по состоянию и ревизии
+   (цель достигнута, ревизия ровно на 1 больше нашей и постановка та же —
+   подтверждено; цель достигнута, но ревизия или постановка ушли дальше —
+   `conflict`; ревизия прежняя — не применено; ревизия
+   сменилась без нашей записи — `conflict`). Ответ `conflict` получателя
+   никогда не лечится повтором старой команды по новой ревизии.
+5. **Подтверждённый отказ ≠ неизвестный исход.** Структурный отказ
+   получателя (`refused`; `conflict` для записи без CAS — комментария;
+   `unavailable` до отправки) означает, что мутации не было: шаг остаётся
+   `planned`, доставка — `failed` с причиной «подтверждённый отказ
+   получателя», повтор `source-deliver` безопасен (тот же маркер). Класс
+   ответа задаёт адаптер: 5xx/ненулевой exit без доказательства отката для
+   мутации адаптер сообщает как `uncertain`, и тогда действует п. 6.
+6. **`uncertain`.** Если исход доказать нельзя (0 маркеров после возможной
+   отправки, больше одного, read-back недоступен), операция получает
+   `uncertain` (событие `delivery.uncertain` с ключом операции), повторная
+   доставка ничего не отправляет до `source-reconcile`.
+7. **Receipt.** После подтверждения всех шагов сохраняется receipt (ID
+   комментария, критерии, колонка, ревизия, сессии истории); для принятого
+   результата — доверенный receipt для зависимых задач.
+
+Повторная доставка принятого результата не вызывает writer/reviewer, не
+запускает gates и не меняет Git. Частично выполненная доставка продолжается
+с первого неподтверждённого шага без повтора append-only записей.
+
+### Один владелец доставки
+
+Владение операцией — lease с токеном, сроком и fencing в SQLite состояния
+коннектора (`BEGIN IMMEDIATE`). Живой владелец продлевает lease и во время
+долгого вызова; второй процесс над тем же каталогом получает
+`CONTROLLER_BUSY` и ничего не отправляет. Упавшего владельца можно
+перехватить только после истечения срока, intent при этом не теряется;
+каждая запись проверяет lease в той же транзакции, поэтому процесс,
+потерявший владение, больше ничего не записывает. Срок `limits.leaseMs`
+должен превышать таймаут одного вызова транспорта.
+
+**Граница гарантии:** она действует только для процессов, разделяющих один
+каталог состояния коннектора. Независимые установки с разными каталогами
+состояния вне гарантии и могут доставить одну операцию дважды —
+`source-check` и `source-status` показывают это в `ownership`. Distributed
+lock в этой версии не реализован.
+
+### Что гарантируется, а что нет
+
+Доказывается тестами (`tests/connector-*.test.ts`, общий набор
+`connectorSuite`):
+
+- одна подтверждённая доставка — один комментарий с маркером, без повторных
+  эффектов критериев и истории, в том числе после перезапуска процесса;
+- обрыв до отправки — безопасный повтор; запись получателем без ответа —
+  read-back без дубля; ответ без сохранённого receipt — без новых мутаций;
+  отказ записи intent — без мутации;
+- неизвестный исход не объявляется успехом и не повторяется автоматически;
+- старая постановка не закрывает новую; чужое изменение между сверкой и CAS —
+  конфликт без повтора;
+- два процесса не отправляют одну операцию одновременно.
+
+**Не гарантируется:** distributed exactly-once — у получателя нет
+идемпотентности по `requestId` (Relay v1 явно её не обещает, у Relay-2 её
+нет), а Git и Relay не образуют общей транзакции. Неоднозначные случаи
+решает оператор.
+
+### Восстановление (`source-reconcile`)
+
+Сначала проверяются факты получателя; решение оператора нужно только там,
+где факты неоднозначны.
+
+| Ситуация                                                                            | Что видно                                   | Действие                                                                                                 |
+| ----------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Запись прошла, ответ потерян                                                        | маркер найден ровно один                    | `source-reconcile --operation <key>` — подтверждение по факту, доставка продолжается                     |
+| Read-back был недоступен                                                            | `uncertain`, причина «read-back недоступен» | повторить `source-reconcile` после восстановления доступа                                                |
+| Таймаут, маркера нет                                                                | 0 маркеров                                  | проверить получателя; если записи нет — `--decision resend` (тот же маркер)                              |
+| Несколько записей с маркером                                                        | N > 1                                       | выбрать одну: `--decision adopt:<commentId>`; первая найденная не выбирается автоматически               |
+| CAS-конфликт без изменения постановки (например, сдвиг ранга соседней задачей в v1) | `conflict`                                  | `--decision recheck`: постановка перечитывается, при совпадении digest шаг продолжается от новой ревизии |
+| Постановка изменилась                                                               | `conflict`, `matchesSnapshot: false`        | результат остаётся историческим; новый `source-snapshot` → согласование → `run --source`                 |
+
+## История работы
+
+При включённой истории (`history.enabled`):
+
+- до исполнения попытки (до вызова writer) — корневая сессия поручения с
+  intent, затем fork дочерней сессии попытки, attach и её intent. Ошибка
+  записи intent — отказ окружения: попытка не начинается;
+- отказ попытки — отмена дочерней сессии; доставка результата — checkpoint с
+  SHA и сводкой gates, завершение и приём дочерней, завершение корня (или
+  отмена при непринятом результате);
+- каждая запись несёт маркер; после перезапуска controller шаги разбираются
+  read-back (`findSessions`, `checkpoints`, ревизия сессии) — без дублей;
+  записи прерванной попытки только подтверждаются фактами и отменяются;
+- ревизия сессии и run backend — fencing: если сессию перехватил другой
+  владелец, устаревший run её не завершает (`conflict`);
+- ID сессии/run backend, sessionId runtime и lease token попытки — разные
+  значения; lease token и полный runtime log в историю не пишутся.
+
+## В Relay уходит
+
+Краткий итог: исход, проверяемые SHA (candidate, integration/result), target
+ref, сводка gates (без журналов), таблица критериев → gate/testcase →
+результат, semantic digest и CAS-ревизия снимка. Локальные пути заменяются
+пометкой (они не ссылки для другого компьютера), значения секретов политики
+маскируются, полный runtime log и вызовы инструментов не копируются.
+
+## Маскирование секретов
+
+Ошибки транспорта (тело ответа HTTP, stderr CLI) маскируются до того, как
+попадут в отчёт `source-check`, `source-status`, ошибки снимка, причины
+шагов и операций в состоянии коннектора, `lastError` доставки, отказ записи
+истории и вывод CLI. Маскируются значения секретов политики на любом уровне
+(`environment.secrets` политики, репозиториев и tool profiles — по
+окружению controller; для `source-snapshot` укажите `--policy`, иначе
+используется политика каталога состояния) и значения настроек provider с
+именем вида `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*KEY*`.
+
+## Состояние коннектора
+
+`<stateDir>/connectors/<provider>-<hash(projectId)>.sqlite` — отдельная от
+`state.sqlite` база: снимки (manifest и digest), операции доставки (intent,
+шаги, receipt), lease, связи с историей. Это не состояние исполнения: оно
+остаётся единственным — в `state.sqlite` harness.
+
+## Библиотека и договор адаптера
+
+```ts
+import { openConnector } from 'devcontour-harness/integrations/connector';
+
+const connector = await openConnector('connector.json', { stateDir: '../state' });
+const h = Harness.open({ stateDir: '../state', policy, baseDir, hooks: connector.hooks() });
+await connector.snapshot('../snapshot');
+await connector.run(h, { author: 'external' });
+await connector.status(h);
+```
+
+Модуль адаптера (`src/integrations/<adapter>/index.ts`) экспортирует
+`createTransport(settings, options?)` и возвращает `RelayTransport`
+(`src/integrations/connector/transport.ts`). `settings` — объект `relay`
+конфигурации, дополненный `projectId` и `actor` верхнего уровня; для
+`relay-v2-cli` пути `binary` и `config` уже абсолютные (разрешены от каталога
+файла конфигурации). Неверные настройки — `HarnessError('INVALID_INPUT')`.
+
+### Общий набор проверки адаптера
+
+`src/integrations/connector/testing.ts` содержит подделку backend
+(`FakeRelayTransport`, fixture), обёртку точек отказа `faultyTransport` для
+любого транспорта, барьеры (`LocalBarrier`, `FileBarrier`) и общий набор
+`connectorSuite(backend)` — W02–W05, D01–D06, R04. Backend набора
+(`SuiteBackend`) создаёт изолированный проект (`project()`), даёт транспорт,
+действия «другого участника» (`admin`) и способ воссоздать транспорт в новом
+процессе (`worker: { kind: 'config' }` — через `createTransportFor`).
+Crash/restart и гонки выполняются в отдельных процессах
+(`testing-worker.ts`) над тем же каталогом состояния. <!-- repo-only -->Набор на подделке —
+`tests/connector-suite.test.ts`; на настоящих Relay v1/Relay-2 —
+`tests/integration/*.test.ts` (репозиторий harness).<!-- /repo-only -->

package/docs/contracts.md

@@ -103,6 +103,7 @@ result SHA доступен в target ref.
 | `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_*` политика задать не может.
@@ -211,7 +212,17 @@ Runtime возвращает сырой ответ; движок разбира
 а не самооценка writer. Reviewer называет состояние каждой прежней открытой
 находки (`previous[]`); `reviewIssues` отклоняет `approved` при блокирующей
 находке, в том числе прежней открытой, неназванную прежнюю находку и ссылку на
-неизвестную. Идентичность находки — `findingId(subject, {rule, message})`.
+неизвестную. Идентичность находки плана/контракта — `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).
 
 ## Выходы
 
@@ -282,7 +293,7 @@ Runtime возвращает сырой ответ; движок разбира
 
 Подлинность SHA, деревьев, artifacts и записей (их наличие в Git и в
 хранилище исполнителя) получатель не удостоверяет — это транспорт хоста.
-Таблица — проверяемое утверждение: `tests/receipt-trust.test.ts` по JSON
+Таблица — проверяемое утверждение: <!-- repo-only -->`tests/receipt-trust.test.ts`<!-- /repo-only --> по JSON
 Schema строит подделку каждого поля (другое значение, удаление
 необязательного поля, пустой массив, повтор и удаление элемента) на двух
 фикстурах и требует отказа для первых двух категорий и того же вердикта для
@@ -386,6 +397,20 @@ Schema строит подделку каждого поля (другое зн
 | `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`                                   | сведение            | сводка находок                                                                                        |
@@ -393,6 +418,8 @@ Schema строит подделку каждого поля (другое зн
 | `findings[].path`                                       | сведение            | сводка находок                                                                                        |
 | `findings[].line`                                       | сведение            | сводка находок                                                                                        |
 | `findings[].rule`                                       | сведение            | сводка находок                                                                                        |
+| `findings[].id`                                         | сведение            | сводка находок                                                                                        |
+| `findings[].status`                                     | сведение            | сводка находок                                                                                        |
 | `limitations`                                           | сведение            | чего результат не доказывает                                                                          |
 | `limitations[]`                                         | сведение            | чего результат не доказывает                                                                          |
 | `finishedAt`                                            | сведение            | время окончания                                                                                       |
@@ -479,8 +506,9 @@ manifestDigest, impact?, evidence[], error?}`. Смена любого SHA де
 (`implementation`, `<фаза>-test:<gate>`, `<фаза>-consumer:<репозиторий>:<gate>`,
 `<фаза>-review`, `<фаза>-environment:<шаг>`, `integration-wait`) и сохраняет
 снимок контекста артефактом `implementation/context.json`. Отказ приёмки с
-кодом `GATE_FAILED`, `REVIEW_REJECTED`, `SCOPE_VIOLATION` или
-`BUDGET_EXHAUSTED` записывается классом отказа этого правила.
+кодом `GATE_FAILED`, `REVIEW_REJECTED`, `REVIEW_PROTOCOL_INVALID`,
+`SCOPE_VIOLATION` или `BUDGET_EXHAUSTED` записывается классом отказа этого
+правила.
 
 Хост, ведущий движок поверх своего хранилища, собирает исполнение из
 экспортов корня пакета: `Engine`, `Runner`, `WorkflowQueue`, `JointRunner`,
@@ -514,7 +542,7 @@ exit code CLI.
 | 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`, `SANDBOX_UNAVAILABLE`, `GIT_FAILED`, `STORAGE_FAILED`, `DELIVERY_FAILED`, `INTERNAL`                                                                                                                       |
+| 4    | `infrastructure` | `STATE_VERSION_UNSUPPORTED`, `RUNTIME_UNAVAILABLE`, `REVIEW_PROTOCOL_INVALID`, `SANDBOX_UNAVAILABLE`, `GIT_FAILED`, `STORAGE_FAILED`, `DELIVERY_FAILED`, `INTERNAL`                                                                                            |
 
 Exit 1 не используется: им Node завершает процесс при необработанном
 исключении.