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

package/docs/turbo-starter.md

@@ -0,0 +1,269 @@
+# Turbo Starter: рецепт и lifecycle-мост
+
+Это первый продуктовый сценарий harness на настоящем pnpm/Turborepo-проекте.
+В копию [Turbo Starter](https://github.com/oim-dev/turbo-starter) на commit
+`78f1e76b80f76ae9d4289e0b0994df8a6f2b89cc` вносится небольшое изменение
+контракта backend. OpenAPI и SDK генерируются штатной командой starter, затем
+проверяется frontend-потребитель. Всё, чего нет в upstream (приёмочные
+проверки с JUnit, политика, граф, мост Docker, шаблоны env), лежит в
+`examples/turbo-starter/` пакета. Upstream не патчится.
+
+| Файл                                           | Назначение                                                                                                                                             |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `examples/turbo-starter/policy.json`           | Политика основного сценария: `prepare` (`pnpm install --frozen-lockfile --offline`), gates, защищённые пути, toolchain (`pnpm 11.25.0`, `node >=24.3`) |
+| `examples/turbo-starter/graph.json`            | Поручение `issued-at`: область записи, gates, контекст `controller-mode`                                                                               |
+| `examples/turbo-starter/policy.lifecycle.json` | Политика с lifecycle `compose-bridge` (PostgreSQL на попытку и фазу)                                                                                   |
+| `examples/turbo-starter/harness/`              | Копируется в `.harness/` проекта: `compose-bridge.mjs`, `compose.acceptance.yml`, `env/*.template`, `acceptance/*.test.mjs`                            |
+| `examples/turbo-starter/changes/*.patch`       | Подготовленные изменения для fixture writer: `issued-at.patch` (верное, вместе с выходом генератора) и `issued-at-consumer-only.patch` (несовместимое) |
+| `templates/controller-mode/`                   | Оверлей `AGENTS.controller.md` v1 и инструкция включения                                                                                               |
+
+## Как повторить
+
+Всё нужное лежит в npm-архиве (`examples/turbo-starter/`, `templates/controller-mode/`);
+checkout исходников harness не требуется. После `npm install devcontour-harness`:
+
+```sh
+# 1. Копия starter + настройка (отдельный baseline-коммит) + pnpm 11.25.0 в <work>/tools,
+#    рядом — policy.json, graph.json и context/controller-mode/ (оверлей с provenance)
+node node_modules/devcontour-harness/examples/turbo-starter/setup.mjs \
+  --work ./ts --source https://github.com/oim-dev/turbo-starter
+# 2. Обычный путь harness (writer/reviewer — настоящие codex/claude из PATH)
+cd ts && export PATH=$PWD/tools/node_modules/.bin:$PATH   # npx найдёт harness проекта выше по дереву
+npx harness validate --graph graph.json --policy policy.json
+npx harness run --graph graph.json --policy policy.json --state state --sink file:results
+npx harness result --state state --work issued-at
+```
+
+Источник можно заменить локальным зеркалом (`--source <path>` или
+`STARTER_SOURCE`). Копия клонируется с `--no-local`, после clone у неё
+удаляется `origin`, поэтому источник не меняется. Настройка из `.harness/`
+фиксируется отдельным коммитом `fixture: devcontour-harness
+turbo-starter-setup/v1` с фиксированными автором и датой. При одинаковых
+входах получается один и тот же baseline SHA. Манифест копии
+(`<work>/fixture.json`) записывает upstream, baseline и sha256 каждого
+файла настройки.
+
+`--warm` один раз прогревает pnpm store и dlx-кэш генератора
+(`@gromlab/rest-api-codegen@5.2.4`) на основном checkout копии. Без
+прогрева `pnpm install --offline` в попытке на холодной машине упадёт с явной
+ошибкой.
+
+### Библиотека подготовки (для W01 и своих сценариев)
+
+`examples/turbo-starter/setup.mjs` (только встроенные модули Node, запускается
+обычным `node`, импортируется как ES-модуль):
+
+- `prepareStarterFixture({ workDir, source?, commit?, installPnpm?, warm? })`
+  возвращает `{ repo, baselineSha, upstream, pathPrepend, env, manifest }`.
+- `starterPolicy(fixture, { template?, targetRef?, scenario?, repoPath?, edit? })`
+  возвращает политику примера. `scenario` подключает fixture runtime
+  (`FIXTURE_SCENARIO`).
+- `starterGraph({ edit? })` возвращает граф примера, например для
+  отображения поручения Relay.
+- `changeFiles(fixture, 'issued-at.patch')` возвращает файлы изменения
+  (`путь → содержимое`) для шага fixture writer.
+- `controllerContext(fixture, dir)` создаёт источник контекста
+  `controller-mode` с provenance; `writeLayout(fixture, options?)` пишет
+  `policy.json`, `graph.json` и контекст рядом с копией.
+- `approve()` и `implement(files)` возвращают шаги сценария управляемых
+  (fixture) runtime для повторяемых прогонов без модели.
+
+<!-- repo-only -->
+
+В checkout harness типы библиотеки — `scripts/acceptance/starter-fixture.d.mts`;
+`scripts/acceptance/starter-fixture.mjs` реэкспортирует её для сценариев
+приёмки, fixture runtime — `tests/fixtures/bin/fake-*`. Это инструменты
+разработки harness, в архив они не входят.
+
+<!-- /repo-only -->
+
+## Gates и кэш
+
+| Gate                    | Команда                                                                       | Что доказывает                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `backend-types`         | `pnpm --filter @oim/nest-backend check-types`                                 | Backend компилируется (`prisma generate && tsc --noEmit`)                        |
+| `sdk-generation` (test) | `node --test --test-reporter=junit … .harness/acceptance/generation.test.mjs` | Закоммиченные OpenAPI и оба SDK совпадают с выходом `pnpm rest-api-sdk:generate` |
+| `sdk-build`             | `pnpm --filter @oim/client-rest-api-sdk run build`                            | Web импортирует SDK из `dist`                                                    |
+| `web-types`             | `pnpm --filter @oim/next-web-app run check-types`                             | Потребитель frontend типизирован против SDK                                      |
+| `acceptance` (test)     | `node --test --test-reporter=junit … .harness/acceptance/issued-at.test.mjs`  | 5 testcases: поле в OpenAPI и SDK обоих realm, потребитель                       |
+
+- JUnit пишет встроенный reporter Node 24, отдельные зависимости не нужны.
+  Отчёты лежат в `.artifacts/junit/` (ignored в starter). Harness удаляет
+  старый отчёт до запуска и принимает только свежий непустой отчёт на
+  проверяемом SHA.
+- Turbo-кэш не участвует. Gates вызывают pnpm-фильтры напрямую, поэтому
+  результата из кэша (cache hit) нет. Каждая попытка ставит свои
+  `node_modules` в своём worktree. Общими между попытками остаются только
+  неизменяемый pnpm store и dlx-кэш. Если gate вызывает `turbo run`,
+  передавайте `--force`, иначе cache hit не докажет свежести.
+  `pnpm exec turbo` предварительная проверка toolchain сейчас отклоняет:
+  `turbo ^2.11.6` в package.json starter не закреплён, хотя lockfile
+  закрепляет 2.11.6.
+- Gate `acceptance` поставляется примером, а не upstream:
+  `apps/nest-backend/AGENTS.md` запрещает добавлять тесты в backend.
+
+## Генерация и область записи (S02)
+
+`generatedPaths` в harness означает «защищено»: путь из этого списка не
+даёт права его менять. Поэтому выходы генерации OpenAPI и SDK туда **не**
+входят. Схема такая:
+
+1. **Явное разрешение поручения.** `writeScope` поручения включает исходники
+   изменения и выходы генерации:
+   `apps/nest-backend/openapi`, `packages/{client,admin}-rest-api-sdk/src/generated`.
+   Без этого изменение генерации отклоняется как выход за область.
+2. **Защита входов генератора.** `protectedPaths` включает
+   `apps/nest-backend/src/export-openapi.ts`, `package.json` обоих SDK, где
+   закреплена версия codegen, lockfile, `.harness/` и AGENTS.md. Попытка не
+   может подменить генератор или проверку.
+3. **Доказательство детерминизма.** Gate `sdk-generation` на candidate и на
+   integration SHA запускает штатную генерацию и сверяет `git diff` и
+   неотслеживаемые файлы по каждому пути выхода. Затем он возвращает
+   дерево к проверяемому коммиту. Устаревший или вручную правленый выход
+   отклоняется с указанием пути.
+4. **`generatedPaths` по назначению.** Там остаётся только
+   `apps/nest-backend/src/generated`, клиент Prisma. Его никто не правит и не
+   коммитит (он ignored).
+
+Проверки области и защищённых путей не выключаются. Защищённый путь важнее
+`writeScope`.
+
+## Lifecycle-мост для существующего worktree (S03, S04, S06)
+
+Starter-команды `worktree:create`/`worktree:up` требуют собственный реестр
+`~/worktrees/.state` и свой каталог worktree. Harness их не вызывает и реестр
+не подделывает. Worktree создаёт harness. `compose-bridge.mjs` поднимает
+среду для уже существующего дерева через шаги lifecycle политики:
+
+```json
+"lifecycle": {
+  "setup":    [{ "id": "compose-setup",    "command": ["node", ".harness/compose-bridge.mjs", "setup", "--port", "POSTGRES_PORT", "--env", ".harness/env/compose.env.template:compose.env", "--secret", "HX_DB_PASSWORD"] }],
+  "ready":    [{ "id": "compose-ready",    "command": ["node", ".harness/compose-bridge.mjs", "ready", "--timeout-ms", "120000"] }],
+  "teardown": [{ "id": "compose-teardown", "command": ["node", ".harness/compose-bridge.mjs", "teardown"] }]
+}
+```
+
+Gates, которым нужна база, запускаются через
+`node .harness/compose-bridge.mjs exec -- <команда>`. Команда получает
+переменные env-файлов среды и `HX_PROJECT`.
+
+- **Каталог среды.** Harness передаёт шагам lifecycle, `prepare` и gates
+  фазы переменную `DEVCONTOUR_ENVIRONMENT_DIR` (псевдоним
+  `HARNESS_ENVIRONMENT_DIR`): `<state>/artifacts/<run>/<phase>/environment`.
+  Это каталог вне worktree, рядом с receipt harness `environment.json`.
+  Переменная сохраняется в receipt, поэтому повторная очистка в новом
+  процессе видит тот же каталог. Состояние моста лежит в `bridge/`:
+  `receipt.json`, `compose.json` (модель без подстановки значений),
+  `labels.json`, `env/*.env` (0600) и `diagnostics/`.
+- **Уникальность.** Проект называется
+  `hx-<runId 12>-<phase>-<repository>`, своё имя на каждую попытку и фазу.
+  Порты выделяются свободными на `127.0.0.1` и отмечаются в реестре моста
+  (`$TMPDIR/devcontour-compose-bridge/ports`). Это защищает от гонки
+  «порт выделен, но ещё не занят». Тома и сеть принадлежат проекту.
+- **Владение.** Каждый сервис, том и сеть получают метки
+  `devcontour.harness.run`, `devcontour.harness.phase`,
+  `devcontour.harness.repository` и `devcontour.harness.project`. Модель
+  проверяется до создания: `container_name`, bind mount, внешние тома и
+  сети, `network_mode: host` и `privileged` отклоняются.
+- **Порядок.** setup (намерение в receipt → порты → env → `compose create`)
+  → ready (`up -d --wait --wait-timeout`) → `prepare` → gates → ревью →
+  teardown. До ready gates не запускаются. При отказе ready сохраняются
+  `ps` и `logs` с замаскированными секретами.
+- **Очистка.** Сначала выполняется `compose down --volumes --remove-orphans`
+  по снимку модели. Затем то, что осталось, удаляется по меткам, причём
+  только при совпадении обеих меток, run и project. `docker prune` не
+  вызывается, контекст Docker не меняется, чужие контейнеры и тома не
+  трогаются. Env-файлы удаляются при любом исходе teardown. Receipt
+  сохраняет, что удалено и что осталось.
+- **Окружение и секреты.** Шаги и gates получают только `inherit/values/secrets`
+  политики, переменные harness `DEVCONTOUR_*` и `HARNESS_*` и минимальную
+  базу (`PATH`, `HOME`, `TMPDIR`, `USER`, `LOGNAME`, `CI`); test-gates
+  дополнительно получают от harness `TURBO_FORCE` и `GOFLAGS=-count=1`
+  (свежесть, не секреты). Секрет задаётся
+  именем переменной оператора (`"secrets": {"HX_DB_PASSWORD": "HX_DB_PASSWORD_SOURCE"}`).
+  Его значение маскируют harness (логи шагов и gates, evidence, итог) и мост
+  (диагностика). В receipt попадают только имена переменных env-файлов.
+
+### Порядок принятия и очистки (S04)
+
+Harness принимает попытку **после** teardown. Teardown candidate и integration
+выполняются до CAS-продвижения target ref. Отсюда:
+
+- сбой setup, ready или gates означает, что попытка не принята, а
+  teardown выполняется всё равно;
+- сбой teardown тоже означает отказ (`CleanupFailure`). Target ref не
+  двигается, и Git-история не переписывается. Receipt получает статус
+  `cleanup-failed`, а в `cleanup-pending.json` перечисляются сохранённые
+  worktree. Ресурсы среды остаются, и это видно;
+- если процесс убит при активной среде, receipt остаётся `active`. Новый
+  процесс с тем же state вызывает `Harness.cleanup(runId)`
+  (`Runner.finishCleanup`). Тот истекает попытку с просроченной арендой,
+  повторяет teardown по receipt только при мёртвом владельце и убирает
+  worktree. Повторный вызов безопасен и возвращает `nothing-pending`.
+  Evidence и логи сохраняются. Пример запуска (поставляется в пакете):
+  `node node_modules/devcontour-harness/examples/turbo-starter/cleanup.mjs --state <state> --run <runId>`.
+
+Состояния «принято» и «очистка не завершена» поэтому не совпадают по
+времени: принятая попытка уже прошла очистку своих сред. Остаётся
+единственный случай, когда после принятия не удаляется worktree попытки
+(`reason: remove-failed`). Он доводится той же очисткой и не трогает
+принятый ref.
+
+## Controller mode (S05)
+
+AGENTS.md starter обязывают агента самому создавать worktree, коммитить и
+сливать изменения и вести историю Relay. Под harness эти операции выполняет
+controller. Оверлей `templates/controller-mode/AGENTS.controller.md` v1
+подключается **источником контекста**, а не файлом в репозитории (starter
+запрещает новые `.md` файлы):
+
+- `context/controller-mode/AGENTS.controller.md` содержит неизменённый
+  оверлей. Он вкладывается в запросы writer и обоих reviewer;
+- в `context/controller-mode/references/**/AGENTS.md` лежат копии product
+  AGENTS.md. Они закреплены sha256, но в запрос не вкладываются: worker
+  читает живые файлы своего worktree;
+- `context/controller-mode/provenance.json` содержит версию и sha256
+  оверлея, baseline SHA и blob каждого product AGENTS.md;
+- в каждом поручении указан `"context": ["controller-mode"]`.
+
+Оверлей перечисляет правила, делегированные controller-у: worktree, commit,
+merge, история Relay, `pnpm run setup`, вложенные оркестраторы и `harness`.
+Остальные правила продукта продолжают действовать (архитектура, запрет
+ручных правок generated, lockfile). В запросе worker есть только запрет
+делать commit. Обязанности коммитить в нём нет. Harness проверяет это
+независимо от текста: commit worker-а или смена HEAD дают
+`scope-violation`, и сценарий это проверяет.
+
+## Известные ограничения upstream
+
+- `scripts/check-env.mjs` (`pnpm env:check`, часть корневого `pnpm lint`)
+  падает на Node 24.3.0: `fs.globSync` не находит dotfiles. На Node 24.22.1
+  проверка проходит. Пример корневой `pnpm lint` не использует и обходится
+  явными pnpm-фильтрами. Патч upstream не нужен.
+- `react-admin-panel` `check-types` скачивает `@gromlab/svg-sprites` через
+  `npx --yes`, поэтому нужна сеть. В gates примера этот пакет не участвует.
+- Изоляция gates в примере выключена (`isolation.mode: none`). pnpm store,
+  dlx-кэш и Docker socket лежат вне worktree. Песочница ОС для них
+  потребует отдельного списка путей и доменов.
+
+<!-- repo-only -->
+
+## Сценарии приёмки
+
+| ID            | Скрипт                               | Что выполняется                                                                                                                                                                                |
+| ------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| S01, S02, S05 | `scripts/acceptance/starter-s01.mjs` | Позитивный прогон через operator approval (`review-plan`, `approve`, `run`); несовместимый потребитель; область записи, защищённый путь, устаревший и вручную правленый выход; commit worker-а |
+| S03           | `scripts/acceptance/starter-s03.mjs` | Две параллельные попытки с отдельными базами, барьер read-back, контрольный контейнер fixture                                                                                                  |
+| S04           | `scripts/acceptance/starter-s04.mjs` | Контрольный прогон, сбой setup после create, таймаут ready, сбой gate, сбой teardown, SIGKILL и очистка новым процессом                                                                        |
+| S06           | `scripts/acceptance/starter-s06.mjs` | Canary-значения, отказ с выводом секрета, явный повтор, доставка, поиск canary во всех артефактах                                                                                              |
+
+Обёртка `tests/integration/starter-acceptance.test.ts` проверяет каждый
+сценарий отдельным тестом. Без Docker или источника upstream тест падает с
+`BLOCKED`, а не пропускается. Быстрые тесты без Docker и pnpm лежат в
+`tests/starter-{setup,bridge,lifecycle}.test.ts`.
+
+W01 (оба Relay) — `scripts/acceptance/w01.mjs relay-v1|relay-v2` и
+`tests/integration/w01-relay-{v1,v2}.test.ts`: тот же Starter, публичный CLI
+`source-*`, восстановление доставки и конфликт постановки.
+
+<!-- /repo-only -->

package/docs/upgrade.md

@@ -0,0 +1,202 @@
+# Обновление и откат
+
+Документ описывает, какие форматы поддерживает пакет, как обновить установку
+и как откатиться. Процедуры одинаковы для standalone-состояния harness и для
+хоста, который держит состояние в своём хранилище (например, DevContour с
+центральной базой или базами компонентов).
+
+## Версии
+
+| Что             | Правило                                                                     |
+| --------------- | --------------------------------------------------------------------------- |
+| Пакет           | `0.1.0-alpha.N`; выпущенная версия неизменяема (тот же номер — те же байты) |
+| Публичный API   | `devcontour-harness/v1alpha1`                                               |
+| Политика        | `policyVersion: 1`                                                          |
+| Состояние       | `stateVersion: 1`                                                           |
+| Отчёты и корпус | `version: 1` (отчёт свойств, договор проверки, корпус, receipt среды)       |
+
+Для `0.x`: patch — совместимые исправления; minor — отдельно описанные
+изменения договора, включая несовместимые. Неизвестная версия входа, политики
+или состояния отклоняется до любой записи и до выдачи попытки.
+
+## Матрица форматов
+
+| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6 | Пишет поверх | Примечание                                                                                                                                               |
+| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | -------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| standalone `stateVersion: 1` версией alpha.1                                   | да                       | да                       | да                   | да           | одна база SQLite: документ, события, локальные записи                                                                                                    |
+| хост, центральная база                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)   | да           | данные не переносятся; новые поля необязательны                                                                                                          |
+| хост, базы компонентов                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)   | да           | нужна копия всех баз при остановленных writers                                                                                                           |
+| alpha.2 после штатной остановки controller                                     | да                       | да                       | да                   | да           | роль controller снята — нового поля в состоянии нет                                                                                                      |
+| alpha.2 с живой или брошенной ролью controller                                 | **нет**, отказ до записи | да                       | да                   | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию                                                                      |
+| alpha.4 с совместной проверкой                                                 | **нет**, отказ до записи | **нет**, отказ до записи | да                   | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию                                                                         |
+| alpha.6 standalone с записями ревью нового протокола или доставкой `uncertain` | **нет**, отказ до записи | **нет**, отказ до записи | да                   | —            | `reviewRound`, `findings[].id/status`, статус доставки `uncertain`; alpha.4/alpha.5 отказывают `STATE_VERSION_UNSUPPORTED` до записи → откат через копию |
+| alpha.6, хост DevContour (адаптер alpha.4)                                     | —                        | —                        | да (через адаптер)   | да           | адаптер DevContour alpha.4 открывает такое состояние без отказа и пишет роль controller и события; новые поля сохраняются → для отката всё равно копия   |
+| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                      |
+
+Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи). Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
+формата до записи проверяют тесты совместимости пакета
+<!-- repo-only -->(`tests/compatibility.test.ts`)<!-- /repo-only -->.
+
+Новые версии добавляют только необязательные поля и новые пространства
+локальных записей. Схемы состояния строгие: прежняя версия отклоняет
+незнакомое поле до любой записи, а не сохраняет его молча. Поэтому откат
+пакета «формат совместим» возможен только для состояния без новых полей,
+иначе — восстановление копии (таблица «Откат» ниже).
+
+### alpha.2: версия движка в роли controller
+
+Роль controller записывает версию движка (`engineVersion`). Процесс другой
+версии — и процесс прежней версии, записавший роль без версии, — живую роль
+не перенимает, даже под тем же именем владельца: `harness run` получает
+`CONTROLLER_BUSY` с обеими версиями, выдачи нет. После истечения срока роль
+переходит штатно, а активные попытки прежней версии проходят recovery без
+повторного использования кандидата. Штатная остановка снимает роль целиком.
+
+### alpha.3: версии движка в `doctor`
+
+Формат состояния тот же, что у alpha.2 (столбец alpha.2 матрицы относится и
+к alpha.3). `harness doctor --state D` читает состояние строгой схемой этой
+версии и для совместимого состояния называет версии движка, записавшие его
+(`state.engineVersions`: роль controller и попытки); состояние, которое эта
+версия не читает, отмечается несовместимым без записи.
+
+### alpha.4: открытие без записи и владение попыткой по версии
+
+- Существующее состояние сначала проверяется целиком соединением только для
+  чтения: версия формата и документ строгой схемой. Несовместимое состояние
+  отклоняется до создания таблиц, записи автора (`meta.writer`) и смены
+  journal mode — файл остаётся байт в байт прежним. `harness doctor --state`
+  открывает состояние только для чтения и автором не становится.
+- Операции активной попытки (продление, фаза, evidence, принятие, отказ) и
+  совместной проверки выполняет только движок той версии, что их начал.
+  Другая версия — и попытка без версии, записанная до её появления, — получает
+  `LEASE_STALE` даже с верным token до истечения срока; продолжение — только
+  через истечение и recovery с новым владением.
+- Совместная проверка записывает `engineVersion`; состояние, где она есть,
+  прежние версии не читают (строка матрицы выше), поэтому откат с alpha.4 на
+  более раннюю версию после первой совместной проверки — только через копию.
+
+### alpha.5: публикация в npm
+
+Код движка, форматы состояния, политики, отчётов и публичный API те же, что
+у alpha.4; меняются поставка (npm, тег `alpha`) и номер версии. Состояние
+alpha.4 alpha.5 читает и пишет без преобразования, состояние alpha.5 читает
+alpha.4 (новых полей нет).
+
+Номер версии — это `engineVersion`, поэтому правила alpha.2–alpha.4
+действуют и между alpha.4 и alpha.5:
+
+- живая роль controller alpha.4 не переходит к alpha.5 (`CONTROLLER_BUSY`),
+  пока не будет снята штатной остановкой или не истечёт;
+- активную попытку и совместную проверку, начатые alpha.4, alpha.5 не
+  продолжает даже с верным token (`LEASE_STALE`): после истечения срока
+  recovery передаёт их новой версии без повторного использования кандидата
+  прежней версии;
+- в обратную сторону то же: после отката alpha.4 не продолжает попытки
+  alpha.5.
+
+Поэтому обновление — по общей процедуре ниже: остановить writers, сделать
+копию, проверить её новой версией. У хоста, который поставлял alpha.4
+архивом, переход на registry — смена зависимости на точную версию
+`0.1.0-alpha.5` и обновление lock; содержимое alpha.4 под своим номером не
+меняется.
+
+### alpha.6: протокол ревью, доставка `uncertain`, toolchains
+
+Формат `stateVersion: 1` прежний; добавлены только необязательные поля, но
+строгие схемы прежних версий их не знают:
+
+- записи ревью кода несут `reviewRound` и `findings[].id/status` (протокол
+  ревью, [review-protocol](review-protocol.md)); такая запись появляется после
+  первого ревью кода новой версией;
+- запись доставки может иметь статус `uncertain` и поле `operation`; в журнале —
+  событие `delivery.uncertain`.
+
+Состояние alpha.5 alpha.6 читает и продолжает без преобразования: прежние
+записи ревью — legacy-раунды, прежние доставки и receipts не переписываются.
+Standalone-состояние, в котором есть новые поля, alpha.5 и alpha.4 не читают:
+отказ `STATE_VERSION_UNSUPPORTED` до любой записи. Прежний хост DevContour
+(0.4.0-alpha.7 с адаптером alpha.4) такого отказа **не даёт**: состояние alpha.6
+— и без записей ревью нового протокола, и с ними (`reviewRound`,
+`findings[].id/status`) — он открывает и может записать в него роль controller,
+события и документ, а при готовых поручениях — выдать по ним работу; новые поля при этом сохраняются, но гарантии строгой схемы
+нет. Пока действует роль controller alpha.6, прежний writer её не перехватывает
+и ничего не пишет. Защиты от запуска прежнего DevContour на состоянии alpha.6
+нет, поэтому откат с alpha.6 — только восстановлением копии состояния,
+сделанной до обновления; прежнюю версию на текущее состояние не запускать.
+
+Правила `engineVersion` (alpha.2–alpha.5) действуют и между alpha.5 и alpha.6:
+живая роль и активные попытки alpha.5 не продолжаются до истечения срока и
+recovery.
+
+Политики: новые необязательные поля `repositories[].toolchain` и
+`reviewProtocolRetries`. Политика без них сохраняет прежние `policyDigest`,
+`executionDigest` и закрепления; политика с ними получает новое основание
+(новое согласование). Встроенные профили alpha.5 побайтно прежние; новые
+профили — новые id (`npm-ci`, `pnpm-frozen`, `go-gotestsum`, `python-uv`).
+
+## Перед обновлением
+
+1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
+   дождаться завершения или явно остановить активные попытки, остановить
+   controller, сервер и всех остальных, кто пишет в состояние. Одной паузы
+   очереди недостаточно.
+2. **Зафиксировать.** Версии пакета и потребителя, конфигурацию, вершины
+   target refs и result SHA принятых поручений (`git rev-parse` каждого
+   target ref, `harness result` каждого поручения).
+3. **Сделать копию.**
+   - standalone — каталог `--state` целиком, пока controller остановлен;
+   - центральная база хоста — штатная согласованная копия SQLite;
+   - базы компонентов — копия **всех** баз при остановленных writers
+     (команда резервной копии одной базы этого не обеспечивает).
+     Git-объекты должны оставаться доступными: копия базы без объектов, на
+     которые она ссылается, не восстанавливает историю.
+4. **Проверить на копии.** Открыть копию новой версией в отдельном каталоге
+   (`harness doctor --state <копия>`, `harness status --state <копия>`).
+   Проверка несовместимой версии не должна менять данные — сравните хэши
+   файлов копии до и после.
+
+## Обновление
+
+1. Установить новую версию точно (у хоста — смена зависимости и lock):
+   - из npm — `npm install --save-exact devcontour-harness@<new>`;
+   - из архива — `npm install --omit=dev --ignore-scripts ./devcontour-harness-<new>.tgz`.
+2. `harness doctor --state D` — версии, runtime, песочница, совместимость и
+   версии движка, записавшие состояние (`state.engineVersions`: роль
+   controller и попытки).
+3. Возобновить работу **одним** controller (`harness resume`, `harness run`).
+4. Попытки, активные во время остановки, не продолжаются со старыми
+   токенами: recovery либо принимает сохранённый integration SHA при полных
+   актуальных evidence, либо завершает попытку; новая попытка получает новое
+   владение и новые проверки. Кандидат попытки прежней версии движка повторно
+   не используется.
+
+Установка новой версии не меняет политику, профили, закрепления контекста,
+инструкции агентам и принятые результаты.
+
+## Откат
+
+| Ситуация                              | Действие                                                                                                                                                        |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Изменения исходников до выкатки       | Вернуться к проверенной паре коммитов/версий в отдельном checkout или revert-коммитами; страховочную ветку не переписывать                                      |
+| Только пакет, формат данных совместим | Остановить writers → вернуть прежнюю версию (архив или точную версию npm), зависимость и lock → `harness doctor` → возобновить                                  |
+| Новая версия уже изменила формат      | Остановить writers → восстановить согласованную копию вместе с совместимой версией пакета → сверить Git refs и артефакты (ниже); простого понижения версии мало |
+
+### Сверка Git после восстановления базы
+
+База и Git не образуют одну транзакцию. Если после копии target ref ушёл
+вперёд (поручение принято уже новой версией), восстановленная база не знает
+об этом принятии.
+
+1. Для каждого репозитория сравните вершину target ref с зафиксированной до
+   обновления и с result SHA, известными восстановленной базе.
+2. Коммиты, которых база не знает, — принятые после копии. Их нельзя молча
+   «забыть»: либо повторите поручения новой попыткой (её интеграция
+   продолжит текущий target ref), либо явно задокументируйте, что эти
+   принятия выполнены вне восстановленного состояния.
+3. Не выполняйте `git reset --hard` пользовательского репозитория и не
+   переписывайте target ref ради совпадения с базой — это не откат, а потеря
+   принятой работы.
+
+Откат объявляется успешным, только когда для каждого target ref известно,
+какие его коммиты учтены восстановленным состоянием.

package/examples/README.md

@@ -0,0 +1,27 @@
+# Примеры конфигурации
+
+Все примеры — вымышленные репозитории с gate `unit` (JUnit). Проверка без
+моделей и записи, из каталога `examples/`:
+
+```sh
+npx harness validate --graph single-task/graph.json --policy two-vendors/policy.json
+npx harness validate --graph single-task/graph.json --policy one-vendor/policy.json
+npx harness validate --graph files-only/graph.json --policy files-only/policy.json
+```
+
+У `files-only/` свой граф с контекстом; политики `two-vendors/` и
+`one-vendor/` подходят к графу `single-task/`.
+
+| Каталог               | Что показывает                                                          |
+| --------------------- | ----------------------------------------------------------------------- |
+| `single-task/`        | одно поручение `add-greeting` — пример быстрого старта                  |
+| `two-vendors/`        | writer claude, reviewer codex для кода, плана и контракта (умолчание)   |
+| `one-vendor/`         | writer и reviewer одного вендора — только с явным `same-vendor-allowed` |
+| `files-only/`         | поручение, контекст и результат только файлами, без внешних сервисов    |
+| `external-connector/` | источник поручений и получатель результата через порты библиотеки       |
+| `turbo-starter/`      | pnpm/Turborepo-проект с генерацией SDK и Docker lifecycle (см. README)  |
+
+Reviewer задаётся правилом ревью явно; неявного «противоположного runtime»
+нет. При `different-vendor` (умолчание) reviewer того же вендора, что автор,
+отклоняется ошибкой `REVIEWER_SAME_VENDOR` до вызова модели. `alternates`
+перечисляет запасных reviewer: берётся первый допустимый для этого автора.

package/examples/external-connector/README.md

@@ -0,0 +1,19 @@
+# Внешний коннектор через порты
+
+`connector.mjs` подключает вымышленный сервис задач как источник поручений
+(`WorkSource`) и получатель результата (`ResultSink`). Политика — как в
+`two-vendors/`. Контекст подключается так же портом `ContextSource`
+(`snapshot(ids, at)` возвращает `ContextSnapshot` с содержимым файлов).
+
+Гарантии не зависят от коннектора:
+
+- граф проходит те же схемы и перекрёстные проверки, что из файла;
+- повтор того же `source.revision` продолжает прежнюю работу, другой digest
+  той же редакции — `REVISION_CONFLICT`;
+- доставка отделена от исхода: принятый код не откатывается из-за
+  недоступного сервиса, повтор доставки идёт с тем же ключом без моделей и
+  интеграции; новая редакция в сервисе получает `conflict`;
+- `trusts` решает только, принимать ли внешний receipt предпосылки; SHA
+  предпосылки всё равно должен быть доступен из target ref.
+
+Подключение нового источника не требует правки движка.

package/examples/external-connector/connector.mjs

@@ -0,0 +1,55 @@
+// Внешний коннектор через порты библиотеки: поручения приходят из сервиса
+// задач, результат возвращается в него же. Движок о сервисе ничего не знает;
+// коннектор не может менять политику, выдавать lease или ставить PASS —
+// у портов нет таких операций.
+import { readFileSync } from 'node:fs';
+import { Harness, executionPolicySchema, workGraphSchema } from 'devcontour-harness';
+
+/** Вымышленный сервис задач: `GET /plans/:ref`, `PUT /results/:workId`. */
+const TRACKER = process.env.TRACKER_URL ?? 'http://127.0.0.1:8080';
+
+/** WorkSource: граф и его редакция из сервиса. */
+const source = {
+  id: 'tracker',
+  async fetch(ref) {
+    const response = await fetch(`${TRACKER}/plans/${encodeURIComponent(ref)}`);
+    if (!response.ok) throw new Error(`tracker: ${response.status}`);
+    const graph = workGraphSchema.parse(await response.json());
+    return { graph, source: graph.source };
+  },
+  async revision(ref) {
+    const response = await fetch(`${TRACKER}/plans/${encodeURIComponent(ref)}`, { method: 'HEAD' });
+    return response.headers.get('x-revision') ?? undefined;
+  },
+  // Внешним receipts по умолчанию не доверяем; доверие не отменяет проверку
+  // доступности result SHA в target ref.
+  async trusts() {
+    return false;
+  },
+};
+
+/** ResultSink: идемпотентно по ключу; новая редакция в сервисе — conflict. */
+const sink = {
+  id: 'tracker',
+  async deliver({ key, result }) {
+    const response = await fetch(`${TRACKER}/results/${result.workOrderId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json', 'idempotency-key': key },
+      body: JSON.stringify(result),
+    });
+    if (response.status === 409)
+      return { status: 'conflict', currentRevision: response.headers.get('x-revision') ?? '?' };
+    if (!response.ok) throw new Error(`tracker: ${response.status}`);
+    return { status: 'delivered', receipt: response.headers.get('location') ?? undefined };
+  },
+};
+
+const policy = executionPolicySchema.parse(JSON.parse(readFileSync('policy.json', 'utf8')));
+const harness = Harness.open({ stateDir: '../notes-state', policy, baseDir: process.cwd() });
+try {
+  const { graph } = await source.fetch('release-1');
+  const status = await harness.run({ graph, author: 'external', sink, source });
+  console.log(JSON.stringify(status, null, 2));
+} finally {
+  harness.close();
+}

package/examples/files-only/README.md

@@ -0,0 +1,28 @@
+# Только файлы
+
+Поручение — `graph.json`, контекст — каталог `context/<id>/`, результат —
+каталог получателя. Ни сервисов, ни базы задач.
+
+```text
+notes-app/
+  graph.json            поручение add-tags ссылается на контекст "norms"
+  policy.json
+  context/norms/rules.md закрепляется за попыткой целиком
+```
+
+```sh
+npx harness validate --graph graph.json --policy policy.json
+npx harness run --graph graph.json --policy policy.json --state ../notes-state \
+  --sink file:../notes-results
+npx harness result --state ../notes-state --work add-tags
+```
+
+Без `--context` CLI собирает снимок из `context/` рядом с графом: каждый
+источник — подкаталог, файлы закрепляются с digest и содержимым; файлы
+`references/` — справочные. Снимок передаётся writer и reviewer одними и теми
+же байтами, его digest попадает в `result.inputs.contextDigest`. Файлы
+контекста из этого репозитория — защищённые пути попытки.
+
+Получатель `file:D` пишет `D/<workId>.json`. Повтор `harness deliver`
+идемпотентен по ключу и не вызывает моделей или интеграции; если граф
+уже в новой редакции, доставка старого результата — `conflict`.

package/examples/files-only/context/norms/rules.md

@@ -0,0 +1,4 @@
+# Нормы проекта
+
+- Модули экспортируют функции через `export function`.
+- Новые функции покрываются тестом в `test/`.