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

package/docs/review-probes.md

@@ -0,0 +1,120 @@
+# Проверки reviewer (`run_check`) и объявленные gates
+
+Reviewer кода, которому профиль разрешает запускать команды, получает MCP-инструмент
+`devcontour_probe.run_check`. Его исполняет controller: песочница ОС, исходники только для
+чтения, предел на команду, общий бюджет проверок и резерв времени на заключение.
+
+## Два вида вызова
+
+| Вызов                           | Что исполняется                                                                | Куда можно писать                           |
+| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
+| `{"argv": ["node", "-e", "…"]}` | исследовательская команда reviewer, без shell, в корне проверяемого дерева     | только собственный `TMPDIR`                 |
+| `{"gate": "domain"}`            | объявленный gate из эффективной политики: его `command`, `cwd`, окружение фазы | только scratch отчёта controller и `TMPDIR` |
+
+Других полей нет: `env`, `cwd`, `reportPath`, `write`, `scope` и любые неизвестные поля —
+ошибка протокола (`-32602`), ничего не запускается. Можно передать `timeoutMs`, но он только
+уменьшает предел controller. Неизвестный ID и генеративный gate (`property`) — результат
+`rejected`, бюджет не тратится.
+
+Запрос reviewer содержит готовый вызов для каждого объявленного gate, например:
+
+```text
+To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"api"} (one gate per call).
+```
+
+## Что делает controller при `{"gate": "<id>"}`
+
+1. Берёт gate из спецификации probe (копия gates поручения из эффективной политики).
+2. Проверяет `cwd`: реальный путь внутри проверяемого дерева, иначе `rejected`.
+3. Если путь отчёта зашит в argv (см. ниже) — не запускает, возвращает ошибку среды с рецептом.
+4. Создаёт каталог evidence `<каталог ревью>/probe-runs/<runId>/` (вне дерева, без перезаписи) и
+   уникальный scratch `dc-probe-report-*` во временном каталоге системы.
+5. Выставляет `HARNESS_REPORT_PATH` и `DEVCONTOUR_REPORT_PATH` = `<scratch>/<id>.xml`, `CI=1`;
+   у `test` gate ещё `TURBO_FORCE=true` и `GOFLAGS=… -count=1`, как у gate движка.
+6. Запускает команду в песочнице: запись — только в scratch и `TMPDIR`; дерево, `.git`,
+   каталог controller и прежние `.reports/*.xml` закрыты на запись.
+7. Читает отчёт: symlink, жёсткая ссылка, путь вне scratch — `unsafe` (не читается); файл старше
+   запуска — `stale`; не JUnit или без testcases — `corrupt`; нет файла — `missing`.
+8. Сохраняет замаскированную копию отчёта (`<id>.xml`), журнал (`<id>.log`) и `run.json`, затем
+   удаляет scratch. Таймаут и отмена (`notifications/cancelled`) останавливают процессы проверки,
+   evidence сохраняется тоже.
+
+Результат и запись в `probes.jsonl` содержат `runId`, `status`, фактический `argv`, `gate.id`,
+`gate.phase`, `gate.sha`, `gate.cwd`, `gate.controllerEnv` (только имена), `gate.report`
+(`status`, `path`, `digest` — SHA-256 сохранённых байтов, `tests`, `failures`, `skipped`),
+`gate.scratchRemoved` и `log` — журнал controller. `review.json` переносит эти записи в
+`probes`; `reproduction.run` находки ссылается на `runId`, а через него — на журнал.
+
+## Бюджет проверок и авария controller
+
+Бюджет проверок общий на логическое ревью (область, фаза, SHA), включая повторы reviewer и
+рестарт controller. Учёт — журнал `probes.jsonl` каждого вызова:
+
+1. До запуска команды controller резервирует её предел и синхронно пишет строку
+   `{"type":"start","runId","reservedMs","startedAt","pid"}` с fsync. Не удалось записать —
+   `error`/`environment`, команда не запускается.
+2. Команда и все её потомки получают `HARNESS_PROBE_RUN=<runId>`.
+3. Строка исхода (обычная запись запуска) разрешает резерв фактической длительностью.
+4. Новый controller перед следующим вызовом reviewer считает расход: завершённые — по
+   длительности, начатые без исхода — **весь резерв** (время до гибели не известно точно и не
+   больше резерва; засчитывается верхняя граница). Пережившие процессы такого запуска (по метке
+   и их группам процессов) останавливаются, в журнал дописывается
+   `{"type":"abandoned","runId","chargedMs"}`; повторное восстановление расход не меняет, а
+   строка исхода, пришедшая позже, заменяет списание фактом без двойного счёта.
+5. Следующий вызов получает бюджет `budget − spent` и прежний срок логического ревью; остаток
+   меньше секунды — вызов без инструмента проверок.
+
+Ограничение: на macOS `ps -E` не показывает окружение системных бинарников (например,
+`/bin/sleep`); такой процесс останавливается, если он в группе процессов запуска.
+
+## Статусы
+
+| `status`                       | `failure`     | Смысл                                                                                                                                   |
+| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `passed`                       | —             | код 0 и (для gate с отчётом) свежий JUnit без failures и skips                                                                          |
+| `failed`                       | —             | код ≠ 0 или упали testcases: наблюдение о коде                                                                                          |
+| `failed`                       | `report`      | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде                                                |
+| `error`                        | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы |
+| `timeout`, `cancelled`         | —             | команда остановлена вместе с потомками                                                                                                  |
+| `budget-exhausted`, `rejected` | —             | команда не запускалась                                                                                                                  |
+
+Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
+`failure: environment`, не получает `observed`.
+
+**Probe — наблюдение reviewer.** Обязательные gates candidate и integration запускает и
+оценивает движок; probe не записывает evidence gate, не ставит технический PASS и не двигает
+target ref.
+
+## Рецепт: путь отчёта из переменной controller
+
+Gate пригоден для probe, если команда пишет JUnit в `HARNESS_REPORT_PATH` (или
+`DEVCONTOUR_REPORT_PATH`). Gate движка получает ту же переменную с путём `report.path` внутри
+дерева, поэтому рецепт с прежним путём по умолчанию не меняет поведение gate движка.
+
+Controller не ищет и не заменяет подстроки в argv. Если элемент argv целиком или после `=`
+(`--junitxml=…`) совпадает с `report.path` относительно `cwd` gate, probe возвращает
+`error`/`environment` с номером аргумента и рецептом, не запуская команду. Если путь зашит в
+скрипт (package script), запуск идёт, запись в дерево получает EPERM, и результат —
+та же ошибка среды с рецептом.
+
+| Инструмент                                                              | Сейчас в профилях/примерах                                                          | Пригодно для probe                                                                                                                                                                                  |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| demo runner (`test/run-tests.mjs`)                                      | читает `DEVCONTOUR_REPORT_PATH`/`HARNESS_REPORT_PATH`, иначе `.reports/<suite>.xml` | да, как есть                                                                                                                                                                                        |
+| npm (`profiles/npm-ci.json`, `examples/toolchains/npm`)                 | `npm run test` → `--test-reporter-destination=.reports/junit.xml` в package script  | `"test": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=${HARNESS_REPORT_PATH:-.reports/junit.xml} test/*.test.js"`         |
+| pnpm (`profiles/pnpm-frozen.json`, `examples/toolchains/pnpm`, `turbo`) | тот же путь в package script пакета                                                 | то же в script пакета; для вложенного пакета — абсолютный `HARNESS_REPORT_PATH` не зависит от каталога                                                                                              |
+| Go (`profiles/go-gotestsum.json`)                                       | `["gotestsum", "--junitfile", ".reports/junit.xml", "--", "-count=1", "./..."]`     | `["sh", "-c", "GOCACHE=\"${GOCACHE:-$TMPDIR/go-build}\" exec gotestsum --junitfile \"${HARNESS_REPORT_PATH:-.reports/junit.xml}\" -- -count=1 ./..."]`                                              |
+| Python (`profiles/python-uv.json`)                                      | `["uv", "run", "--no-sync", "pytest", "--junitxml=.reports/junit.xml"]`             | `["sh", "-c", "PYTHONDONTWRITEBYTECODE=1 UV_CACHE_DIR=\"${UV_CACHE_DIR:-$TMPDIR/uv}\" exec uv run --no-sync pytest -p no:cacheprovider --junitxml=\"${HARNESS_REPORT_PATH:-.reports/junit.xml}\""]` |
+| mixed-python (`cwd: backend`)                                           | `--junitxml=../.reports/backend.xml`                                                | `--junitxml="${HARNESS_REPORT_PATH:-../.reports/backend.xml}"` через `sh -c`                                                                                                                        |
+
+Рецепты npm, Go и Python проверены на настоящих инструментах под песочницей ОС
+<!-- repo-only -->(`tests/integration/probe-recipes.test.ts`)<!-- /repo-only -->: команда профиля даёт `error`/`environment` (для
+
+npm — после EPERM записи из package script), рецепт проходит в probe со свежим JUnit вне
+дерева и в gate движка с отчётом в дереве. Под `isolation.mode: os` cache Go и uv по умолчанию
+лежит вне доступного на запись, поэтому рецепт направляет `GOCACHE`/`UV_CACHE_DIR` в `TMPDIR`
+(если они не заданы), а pytest — без `.pytest_cache` и байткода в дереве. pnpm и turbo
+используют тот же механизм package script, что и npm; отдельным прогоном не проверялись.
+
+Встроенные профили не меняются (их байты закреплены digest). Для них probe по ID даёт
+проверяемую диагностику вместо EPERM; gate движка работает как прежде. Новый профиль с рецептом —
+новый файл и новый ID.

package/docs/review-protocol.md

@@ -0,0 +1,251 @@
+# Протокол ревью кода: находки, переходы и ошибки протокола
+
+Документ задаёт правила истории находок независимого ревью кода (candidate и
+integration) и отделяет ошибку формата ответа reviewer от содержательного
+отказа. Правила записаны до реализации и являются договором: тесты
+`tests/review-*.test.ts` проверяют именно их.
+
+## 1. Область истории
+
+История находок ведётся **на поручение**, а не на попытку, фазу или SHA:
+
+```
+scope = digestOf({ kind: 'code-review', repositoryId, workId })
+```
+
+- Новая попытка writer, переход candidate → integration и рестарт процесса не
+  начинают историю заново: история каждый раз заново собирается из evidence
+  всех попыток поручения (`ExecutionView.attempts(workId)`) в порядке записи.
+- Отдельного хранилища нет: состояние находок — это записи ревью в
+  `EvidenceRecord` попыток (см. §5). Нового обязательного метода
+  `ExecutionStore`, второй базы или нового пространства локальных записей нет.
+- SHA не является идентичностью истории: после исправления SHA меняется, а
+  находка — нет.
+- Находка другой области (другое поручение или репозиторий) в этой истории
+  неизвестна: ссылка на неё — ошибка протокола `unknown`.
+
+## 2. Идентификатор находки
+
+ID выдаёт controller в момент записи валидного раунда; reviewer его не
+придумывает и ссылается только на выданный. Формат прежний — SHA-256 hex
+(`^[0-9a-f]{64}$`), без ослабления до произвольной строки.
+
+```
+id = digestOf({ v: 1, scope, runId, phase, sha, round, index, severity, message })
+```
+
+`round` — номер валидного раунда области, `index` — позиция находки в ответе.
+Повторно найденный дефект с тем же текстом в новом раунде получает **новый**
+ID: дедупликации по тексту нет, поэтому повторно найденный на integration
+дефект не теряется.
+
+Находка хранит: severity, сообщение, путь/строку, статус (`open`, `closed`,
+`withdrawn`), origin (runId, фаза, SHA, раунд, согласованная постановка
+`spec` на момент записи) и ряд переходов (раунд, runId, фаза, SHA, from → to,
+основание).
+
+## 3. Переходы
+
+Для каждой прежней **открытой** находки валидный ответ называет ровно одну
+запись в `previous` с основанием (`basis`, не короче трёх непробельных
+символов):
+
+| Из                   | В           | Смысл                                                                                  |
+| -------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `open`               | `closed`    | исправление подтверждено на проверяемом SHA                                            |
+| `open`               | `withdrawn` | находка ошибочна или потеряла предмет; основание объясняет почему                      |
+| `open`               | `open`      | дефект остаётся                                                                        |
+| `closed`/`withdrawn` | `open`      | явное повторное открытие (reopen): дефект снова есть, например в интеграционном дереве |
+
+Закрытые и снятые находки передаются reviewer как история и не требуют
+повторного закрытия. Указать для них `closed`/`withdrawn` повторно —
+ошибка `not-open`.
+
+Ответ невалиден (ошибка протокола), если:
+
+| reason                   | path                               | условие                                                                       |
+| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------------- |
+| `schema`                 | путь Zod, например `previous.0.id` | ответ вне схемы: не SHA-256 ID, пустое основание, неизвестный статус, поля    |
+| `unknown`                | `previous.N.id`                    | ID нет в истории области (в том числе ID чужого поручения/репозитория)        |
+| `duplicate`              | `previous.N.id`                    | ID назван второй раз (в том числе с другим статусом)                          |
+| `not-open`               | `previous.N.status`                | закрытой/снятой находке назван не `open`                                      |
+| `missing`                | `previous`                         | прежняя открытая находка не названа                                           |
+| `approved-with-blocking` | `approved`                         | `approved: true` при новой blocking-находке или blocking, оставшейся открытой |
+
+`note`, оставленная открытой явным переходом, не мешает `approved: true`.
+
+**Атомарность.** Ответ проверяется целиком до любой записи. Невалидный ответ
+не закрывает ни одной находки, не создаёт новых и не даёт PASS: он
+сохраняется только как диагностика (сырой ответ — в своём `review.json`,
+причины — в evidence). Валидный раунд записывается одной транзакцией
+`engine.evidence` под fencing-токеном попытки: попытка, потерявшая владение,
+переходов не сохраняет.
+
+## 4. Фазы, повторное открытие и новая редакция
+
+- Закрытие на candidate не означает одобрения integration: integration —
+  отдельный раунд той же области. Reviewer integration получает открытые
+  находки и историю закрытых; найденный там снова дефект блокирует приёмку
+  либо явным reopen прежнего ID, либо новой находкой с новым ID.
+- Приёмка по-прежнему требует последней записи ревью каждой фазы на точном SHA
+  с PASS (`engine.finish`, `findLast`).
+- **Новая редакция постановки/контрактов** (новое согласование того же
+  поручения) не начинает историю заново и не удаляет её. Открытые находки
+  переносятся в новую редакцию открытыми; в их origin видна редакция, под
+  которой они записаны (`spec`). Reviewer новой редакции обязан назвать их
+  состояние, как любые прежние открытые (например, `withdrawn` с основанием
+  «требование удалено редакцией …»). Закрытые остаются историей. Одобрение
+  прежней редакции новую не подтверждает: новая редакция исполняется новой
+  попыткой, и приёмка учитывает только evidence этой попытки.
+- Формулы host digests (`orderDigest`, `policyDigest`, `scopeDigest`,
+  основание реализации и эпизода) не меняются: находки в них не входят.
+
+## 5. Хранение: аддитивные поля EvidenceRecord
+
+DevContour хранит `Evidence` как есть; все новые поля необязательны, старые
+записи читаются без них.
+
+- `findings[].id`, `findings[].status` — ID и статус находки, записанной этим
+  раундом.
+- `reviewRound` — сведения раунда ревью кода:
+  `version: 1`, `scope`, `round`, `call` (номер вызова reviewer в логическом
+  ревью), `calls` (предел вызовов), `protocol: valid | invalid`, `expected`
+  (ID открытых находок, выданных reviewer), `issues` (path, reason, message —
+  у невалидного), `transitions` (id, from, to, basis — у валидного), `spec`.
+
+Результат (`RunResult`) получает аддитивно: `findings[].id/status` и у ссылок
+на evidence ревью — `review` (round, call, protocol, issues, transitions).
+Принятый результат несёт только решающие записи: невалидные вызовы в него не
+входят отдельными ссылками, их причины видны у валидного вердикта повтора
+(`review.call > 1`, `review.issues` — причины предыдущих вызовов того же
+логического ревью). Непринятый результат содержит и записи невалидных
+вызовов (`review.protocol: invalid` с их причинами).
+
+## 6. Записи alpha.5 (legacy)
+
+Запись ревью без `reviewRound` — запись прежней версии. Её находки (у
+отклонившего ревью) получают детерминированный ID из неизменяемого origin:
+
+```
+id = digestOf({ v: 'legacy-1', scope, evidence: e.id, runId, phase, sha, index, severity, message })
+```
+
+После рестарта ID тот же. Находки открыты, пока reviewer явно не назовёт их
+состояние — это явное повторное ревью вместо пустой истории. Принятые
+попытки и их результаты не переписываются: новые поля у них не появляются, и
+исход не меняется задним числом.
+
+## 7. Ошибка протокола и ограниченный повтор reviewer
+
+| Исход                                                                       | Поведение                                                                                    |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Валидный `approved: false`                                                  | `REVIEW_REJECTED`, обычный путь исправления writer                                           |
+| Нарушение схемы/переходов/противоречивый approved                           | повтор reviewer; после исчерпания — `REVIEW_PROTOCOL_INVALID` (класс infrastructure, exit 4) |
+| Reviewer изменил дерево/HEAD, утрачено владение, отмена, смена согласования | соответствующий отказ без протокольного повтора                                              |
+| Runtime недоступен, авторизация, timeout                                    | прежняя инфраструктурная причина, без протокольного повтора                                  |
+
+- Политика: необязательное поле `reviewProtocolRetries` (0–2). Нет поля —
+  один дополнительный вызов (не более двух вызовов на логическое ревью);
+  `0` отключает повтор. Отсутствующее поле не подставляется в политику, её
+  digest и pins не меняются.
+- Логическое ревью — (область, фаза, SHA). Повтор идёт на том же SHA, с тем же
+  diff, контекстом, назначением reviewer и набором открытых находок; к запросу
+  добавляется только структурированная диагностика (path, reason, message) и
+  требование вернуть полный валидный вердикт. ID не подменяются «похожими»,
+  `previous` не выбрасывается, `approved` не восстанавливается догадкой.
+- Writer не вызывается, номер попытки не растёт. Каждый вызов проходит
+  `measuredInvoke` (бюджет до вызова, учёт usage/стоимости, неизвестная
+  стоимость по `budgets.onUnknown`). Повтор не получает нового предела
+  времени фазы и нового бюджета probe: общий срок и остаток бюджета probe
+  переходят от первого вызова.
+- Каждый вызов пишет свои артефакты: первый — `<phase>/review/`, следующие —
+  `<phase>/review/call-<n>/` (`review.json`, журнал runtime, probe). Каждый
+  невалидный вызов записывается своим evidence (`passed: false`,
+  `reviewRound.protocol: invalid`, без находок); итоговое evidence ссылается
+  на байты валидного вердикта.
+- Рестарт не обнуляет счётчик. Вызов засчитывается при **начале**: запись
+  учёта вызова (`usage`, `CallRecord` со `stage: <фаза>-review`, `runId`)
+  создаётся транзакцией `measuredInvoke` до внешнего invoke, поэтому вызов,
+  прерванный падением controller, засчитан так же, как завершённый (после
+  рестарта он помечается `abandoned`). Начатые вызовы того же (область, фаза,
+  SHA) из попыток, прерванных до вердикта (истёкших или с отказом окружения),
+  засчитываются продолжающей попытке (кандидат переиспользуется); для записей
+  без учёта вызовов — по невалидным evidence. Исчерпанный счётчик — остановка
+  `REVIEW_PROTOCOL_INVALID` без вызова. Номер вызова — номер фактически
+  начатого вызова. Логическое ревью закрывают валидный вердикт или иное
+  завершение попытки (в том числе остановка `REVIEW_PROTOCOL_INVALID`).
+- Срок и бюджет проверок после рестарта не выдаются заново: срок логического
+  ревью — `runTimeoutMs` от начала его первого вызова (по записи учёта);
+  истёкший срок — явная остановка `REVIEW_PROTOCOL_INVALID` (класс `review-protocol`, без автоматического повтора) без вызова, а каждому вызову достаётся
+  только остаток срока. Расход бюджета проверок — по журналам `probes.jsonl`
+  прежних вызовов этого логического ревью. Резерв каждой проверки (её предел)
+  записывается в журнал строкой `start` с fsync **до** запуска команды; без
+  этой записи проверка не запускается. Завершённая проверка списывает
+  фактическое время, начатая без строки исхода (controller или сервер проверок
+  погиб посреди команды) — весь резерв, никогда не меньше. Новый controller
+  останавливает пережившие процессы такой проверки (метка `HARNESS_PROBE_RUN`
+  и их группы) и дописывает строку `abandoned`; остаток меньше секунды — вызов
+  без инструмента проверок (docs/review-probes.md). Integration SHA после рестарта
+  создаётся заново (новое слияние), поэтому это новое логическое ревью; его
+  повторы ограничены правилами повтора попытки.
+- Класс отказа попытки `review-protocol`: автоматического повтора нет
+  (`repairPolicy` — stop), для эпизода восстановления по свойству он
+  нейтрален (не увеличивает и не обнуляет счёт), код остановки результата —
+  `REVIEW_PROTOCOL_INVALID`. Кандидат такой попытки переиспользуется
+  повтором, назначенным человеком, без нового вызова writer.
+
+## 8. План и контракт
+
+`technicalReview` (ревью плана и контракта) применяет то же правило
+атомарности: невалидный ответ (вне схемы или с нарушением `reviewIssues`)
+не применяет переходы и не добавляет находок; раунд записывается
+неодобренным с причинами. Повторно найденная закрытая находка с тем же ID
+открывается снова, а не отбрасывается как дубликат. Формат `ReviewRecord`
+не меняется.
+
+## 9. Адаптеры без протокола переходов (совместимость хостов)
+
+Строгие правила §3 действуют, когда адаптер reviewer объявляет
+`RuntimeCapabilities.reviewProtocol: 1`. Это необязательное поле; нового
+обязательного метода нет. `cliAdapter` (codex, claude, в том числе fixture
+executables `HARNESS_*_BIN`) поле объявляет, поэтому пилот, live и demo
+работают строго. Runner читает поле асинхронно до вызова reviewer, вне
+транзакций хранилища, и кэширует его на runtime. Отказ `capabilities()`
+трактуется как адаптер прежней версии.
+
+Адаптер хоста, который поля не объявляет (например, собственные
+runtime-обёртки DevContour), получает семантику переходов alpha.5:
+
+- в запросе нет раздела выданных ID, и в ответе переходы не требуются:
+  ответ проверяется без прежних открытых находок, как прежний
+  `reviewIssues(result, [])`. Ссылка на прежний ID — `unknown`, а
+  `approved: true` с новой blocking-находкой — `approved-with-blocking`;
+- находки записываются в историю открытыми с выданными ID, раунд помечен
+  `reviewRound.mode: 'legacy'`. Закрытия не выдумываются: одобрение не
+  закрывает прежние находки, они остаются в истории открытыми. Одобрение
+  при таких находках — поведение alpha.5 для этого адаптера: прежний адаптер
+  не умеет называть их состояние;
+- разделение H2 сохраняется: ответ вне схемы или противоречивый `approved`
+  даёт ошибку протокола с ограниченным повтором reviewer и
+  `REVIEW_PROTOCOL_INVALID`, а не содержательный отказ;
+- writer такого поручения не получает раздела «открытых» находок: их
+  некому закрыть.
+
+Если позже ревью ведёт адаптер с протоколом, открытые находки legacy-раундов
+требуют явного перехода, как записи alpha.5 (§6).
+
+### Что реализует собственный адаптер с протоколом
+
+1. `capabilities()` возвращает `reviewProtocol: 1`.
+2. Для `task: 'review-code'` запрос несёт `RuntimeRequest.findings`
+   (`{scope, open[], closed[]}`; у находки — `id`, `severity`, `message`, `path`,
+   `line`, `status`, `origin {runId, phase, sha, round}`, `basis?`). Это те же
+   данные, что раздел запроса `Open review findings issued by the controller`,
+   поэтому адаптеру без модели не нужно разбирать текст.
+3. Ответ (`RuntimeResponse.output`, схема `reviewResultSchema` / wire
+   `reviewOutputSchema`) содержит в `previous` ровно одну запись
+   `{id, status: 'open' | 'closed' | 'withdrawn', basis}` на каждую находку
+   `open`. `id` — выданный (SHA-256 hex), `basis` — не меньше трёх непробельных
+   символов. Для `closed` допустимо только `{id, status: 'open', basis}`
+   (повторное открытие). `approved: true` невозможно при blocking-находке,
+   оставленной открытой, или при новой blocking-находке.

package/docs/toolchains.md

@@ -0,0 +1,167 @@
+# Toolchains целевого проекта
+
+Harness — Node.js-инструмент. Исполняемому проекту не нужны package.json, npm или
+JavaScript: gates и шаги подготовки — произвольные argv, каталог gate — `cwd`, окружение —
+`environment`. npm и pnpm — менеджеры пакетов, Turborepo — планировщик задач, Go и
+Python/uv — отдельные toolchain. Единого «типа проекта» нет: репозиторий описывается
+композицией шагов.
+
+| Что                                                             | Где в политике                                                                                                           |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Установка зависимостей (locked)                                 | `repositories[].prepare[]` — исполняется в каждом worktree попытки до writer, отдельно для candidate и integration       |
+| Команды задач и проверки                                        | `repositories[].gates[]` (`check` / `test` с JUnit)                                                                      |
+| Каталог                                                         | `gates[].cwd`; у шага `prepare` — собственный флаг инструмента (`pnpm --dir`, `npm --prefix`, `uv --directory`, `go -C`) |
+| Окружение                                                       | `environment` политики/репозитория (`values`, `inherit`, `secrets`)                                                      |
+| Проверенные версии инструментов и явный выбор менеджера пакетов | `repositories[].toolchain` (`tools`, `packageManagers`), необязательно                                                   |
+
+`toolchain` — необязательное аддитивное поле: политики и профили без него сохраняют прежний
+digest. `tools` — `{ "gotestsum": "1.12.3" }` (названные компоненты версии совпадают) или
+`{ "go": ">=1.24" }` (не ниже). `packageManagers` — `{ ".": "pnpm", "frontend": "pnpm" }`:
+явный выбор снимает неоднозначность, когда в каталоге лежат lockfiles нескольких менеджеров.
+
+## Рецепты
+
+Проверенный набор (macOS arm64, Darwin 24.6): Node 24.3.0, npm 11.4.2, pnpm 10.12.3,
+Turbo 2.11.10 (devDependency fixture), Go 1.24.5, gotestsum v1.12.3, uv 0.11.28,
+CPython 3.12.9 (выбран uv по `.python-version`), pytest 8.4.1, ruff 0.12.4.
+
+| Вариант                        | prepare                                                                                 | gates                                                                                         | Встроенный профиль                                             |
+| ------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Node + npm                     | `npm ci`                                                                                | `npm run check`, `npm run test` (JUnit `.reports/junit.xml`)                                  | `npm-ci@0.1.0`                                                 |
+| Node + pnpm                    | `pnpm install --frozen-lockfile`                                                        | `pnpm run check`, `pnpm run test`                                                             | `pnpm-frozen@0.1.0`                                            |
+| pnpm + Turborepo               | `pnpm install --frozen-lockfile`                                                        | `pnpm exec turbo run check --filter=<pkg>`, `pnpm exec turbo run test --filter=<pkg> --force` | — (фильтры проекта: политика, см. `examples/toolchains/turbo`) |
+| Go                             | `go mod download`                                                                       | `go vet ./...`, `gotestsum --junitfile .reports/junit.xml -- -count=1 ./...`                  | `go-gotestsum@0.1.0`                                           |
+| Python                         | `uv sync --locked`                                                                      | `uv run --no-sync ruff check .`, `uv run --no-sync pytest --junitxml=.reports/junit.xml`      | `python-uv@0.1.0`                                              |
+| pnpm frontend + Go backend     | `pnpm --dir frontend install --frozen-lockfile`, `go -C backend mod download`           | gates с `cwd: frontend` / `cwd: backend`                                                      | — (`examples/toolchains/mixed-go`)                             |
+| pnpm frontend + Python backend | `pnpm --dir frontend install --frozen-lockfile`, `uv sync --locked --directory backend` | gates с `cwd: frontend` / `cwd: backend`                                                      | — (`examples/toolchains/mixed-python`)                         |
+
+Правила рецептов:
+
+- Только locked-установка: `npm ci`, `pnpm install --frozen-lockfile`, `uv sync --locked`,
+  `go mod download`. Несовместимый lockfile — отказ шага с диагностикой менеджера, lockfile
+  не переписывается. `npm install`, `pnpm install` без `--frozen-lockfile`, `uv sync` без
+  `--locked`, `uv run` без `--no-sync`, `go get`, `go mod tidy` — проблема preflight.
+- Точные версии, без `@latest`, `npx`, `pnpm dlx` без версии, `uvx` без версии, `--if-present`.
+  Отсутствующий test task не заменяется build/lint.
+- Отчёт gate лежит относительно корня worktree, а не `cwd`: gate `cwd: backend` пишет JUnit в
+  `../.reports/backend.xml`, gate объявляет `.reports/backend.xml`. Harness удаляет файл
+  отчёта до запуска и передаёт путь в `HARNESS_REPORT_PATH`.
+- Один monorepo — одна запись Git repository с разными `cwd`. `consumers` — только для
+  действительно отдельных репозиториев.
+- Профили языков (`go-gotestsum`, `python-uv`, прежние `go-api`, `python-api`) не наследуют
+  npm-подготовку. Слои профиля с разными версиями одного инструмента или разными менеджерами
+  одного каталога — отказ разрешения (`Конфликт частей профиля: toolchain.…`).
+- Композиция из кода: `composeRepository(own, components, tools)` и `installRecipes` из
+  opt-in entrypoint `devcontour-harness/toolchains`.
+
+## Установка harness для Go/Python-проекта
+
+Target-проекту package.json не нужен. Harness ставится в отдельное окружение инструмента.
+
+npm:
+
+```sh
+mkdir -p ~/.local/share/harness-tool && cd ~/.local/share/harness-tool
+npm init -y >/dev/null
+npm install --save-exact devcontour-harness@<версия>
+export PATH="$PWD/node_modules/.bin:$PATH"
+harness doctor --policy /path/to/project-harness/policy.json
+```
+
+pnpm:
+
+```sh
+mkdir -p ~/.local/share/harness-tool && cd ~/.local/share/harness-tool
+pnpm init >/dev/null
+pnpm add --save-exact devcontour-harness@<версия>
+export PATH="$PWD/node_modules/.bin:$PATH"
+```
+
+Политика и граф могут лежать вне target-репозитория: `repositories[].path` относителен
+каталогу политики (`examples/toolchains/go/policy.json` → `"path": "repo"`).
+
+## Cache и изменяемые каталоги
+
+Каждая попытка исполняется в своём worktree (`<state>/repos/<repo>/worktrees/<attempt>` и
+`…-integration`), и `prepare` устанавливает зависимости заново в нём. Изменяемые артефакты
+одной попытки другой не видны.
+
+| Допустимый общий cache (content-addressed, вне worktree)                                               | Изменяемое, только внутри worktree попытки                       |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| npm cache (`~/.npm`), pnpm store, Go module cache (`GOMODCACHE`), Go build cache (`GOCACHE`), uv cache | `node_modules/`, `.venv/`, `.reports/`, `.turbo/`, выходы сборки |
+
+Cache сборки допустим, но не заменяет тест:
+
+- Во время исполнения каждый gate `kind: test` получает `TURBO_FORCE=true` и `GOFLAGS`,
+  оканчивающийся на `-count=1` (после значения политики). Окружение наследуют все потомки, так
+  что защита действует при любой обёртке (package script, `pnpm --filter … run`, task runner),
+  в библиотечном `Harness.run`/`Runner` и в CLI одинаково. Заголовок лога gate записывает
+  применённые значения (`fresh={...}`); digest лога входит в evidence. `check` gates cache
+  используют как обычно.
+- Turbo: preflight дополнительно требует явной свежести в самой команде — `--force`,
+  `--cache=` без чтения или `TURBO_FORCE=true` — и находит turbo внутри package scripts
+  (напрямую, через `pnpm run`/`npm run`, `pnpm --filter … run`, `pnpm exec`, `npx`). Без неё —
+  `CACHE_REPLAY`. Script turbo-проекта, который не разбирается статически (`$(…)`, обратные
+  кавычки, конвейер, `sh -c`, `eval`, `xargs`), — `SCRIPT_UNRESOLVED`: угадывать нельзя.
+  Проверено T03: при входах задачи без `src` неверная реализация вне harness даёт «cache hit,
+  replaying» и зелёный отчёт; тот же script через gate — «cache bypass, force executing» и
+  отказ, в том числе через общий `TURBO_CACHE_DIR` и `Harness.run` без CLI.
+- Go: команда без `-count=1` в test gate — предупреждение (`warnings`): прежний `go-api`
+  продолжает проходить preflight, а свежесть обеспечивает `GOFLAGS` во время gate.
+
+Isolation `os` пишет только в worktree и временный каталог проверки: для Go/uv/pnpm в
+песочнице cache-каталоги (`GOCACHE`, `UV_CACHE_DIR`, store) нужно указать доступными или
+использовать `isolation.mode: none`, как в примерах. Установка (`prepare`) идёт вне песочницы.
+
+## Диагностика: doctor и preflight
+
+`harness doctor --policy policy.json` (или `--state`) добавляет `toolchains[]` — по
+репозиторию политики:
+
+- `plan` — каждый шаг и gate: фаза, `cwd`, argv, путь отчёта, поле конфигурации;
+- `tools` — внешние инструменты из PATH (найден, версия по пробе, требования и их источник:
+  `toolchain.tools`, `package.json#packageManager`, `go.mod#go`) и инструменты среды проекта
+  (`turbo` из `package.json`: диапазон допустим, если lockfile закрепляет точную версию,
+  иначе `UNPINNED`; `ruff`/`pytest` из `uv.lock`) — последние не запускаются;
+- `lockfiles` — каталоги node-проектов, их lockfiles и выбранный менеджер;
+- `reports`, `ambiguities` (с `resolvedBy`), `problems`, `warnings`, `configSource`.
+
+Каждая проблема — код, поле (`repositories.0.gates.1.command`) и путь файла проекта:
+`TOOL_MISSING`, `TOOL_VERSION`, `TOOL_VERSION_UNKNOWN`, `TOOL_NOT_LOCKED`, `MANIFEST_MISSING`,
+`LOCKFILE_MISSING`, `LOCKFILE_AMBIGUOUS`, `SCRIPT_UNKNOWN`, `TASK_UNKNOWN`, `FILTER_UNKNOWN`,
+`INSTALL_UNLOCKED`, `UNPINNED`, `IF_PRESENT`, `CACHE_REPLAY`, `REPORT_MISMATCH`,
+`COMPOSITION_CONFLICT`, `CWD_MISSING`, `PROJECT_FILE_MISSING`, `REPOSITORY_MISSING`,
+`TOOL_IN_PROJECT`, `SCRIPT_UNRESOLVED`.
+
+Диагностика только читает файлы (package.json, pnpm-workspace.yaml, turbo.json, go.mod,
+pyproject.toml, uv.lock) и запускает пробы версий внешних инструментов: `<tool> --version`
+(`go version`; для Go-бинарника без метки версии — `go version -m <файл>`), в нейтральном
+временном каталоге, по одной на инструмент, с пределом 10 с и одним повтором с пределом 20 с, если проба не
+уложилась во время (нагрузка). Перед пробой путь инструмента
+разрешается до канонического (все symlink файла и каталога PATH): файл внутри любого
+репозитория политики (включая его `node_modules/.bin`, `.venv`) или каталога состояния с
+worktrees не запускается — проблема `TOOL_IN_PROJECT`. Ни установки, ни генерации, ни новых
+файлов.
+
+`doctor` по-прежнему информационный (exit 0, проблемы в `problems`). С политикой он требует
+только runtime, назначенные политикой (`reason: "не назначен политикой"` у остальных).
+`harness run` выполняет ту же диагностику как обязательный preflight: при любой проблеме —
+exit 3, `NOT_READY` с issues `policy.<поле>` до записи `binding.json`, открытия состояния и
+вызова runtime.
+
+## Пример и приёмка
+
+`examples/toolchains/<variant>/` — `repo/` (target-проект; `_gitignore` становится
+`.gitignore`), `policy.json`, `task.json`, `good/` и `bad/` (реализации для fixture writer).
+<!-- repo-only -->
+
+В репозитории harness (не входит в пакет). Сквозной прогон всех семи вариантов через обычный путь harness:
+
+```sh
+node --import tsx scripts/acceptance/t01.mjs            # все варианты
+node --import tsx scripts/acceptance/t01.mjs go python  # выборочно
+```
+
+<!-- /repo-only -->
+
+Нужны npm, pnpm, go + gotestsum, uv в PATH; отсутствующий инструмент — `BLOCKED`.