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

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`.

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

@@ -7,13 +7,13 @@
 
 ## Версии
 
-| Что             | Правило                                                                     |
-| --------------- | --------------------------------------------------------------------------- |
-| Пакет           | `0.1.0-alpha.N`; выпущенная версия неизменяема (тот же номер — те же байты) |
-| Публичный API   | `devcontour-harness/v1alpha1`                                               |
-| Политика        | `policyVersion: 1`                                                          |
-| Состояние       | `stateVersion: 1`                                                           |
-| Отчёты и корпус | `version: 1` (отчёт свойств, договор проверки, корпус, receipt среды)       |
+| Что | Правило |
+| --------------- | --------------------------------------------------------------------------- || --------------------
+| Пакет | `0.1.0-alpha.N`; выпущенная версия неизменяема (тот же номер — те же байты) |
+| Публичный API | `devcontour-harness/v1alpha1` |
+| Политика | `policyVersion: 1` |
+| Состояние | `stateVersion: 1` |
+| Отчёты и корпус | `version: 1` (отчёт свойств, договор проверки, корпус, receipt среды) |
 
 Для `0.x`: patch — совместимые исправления; minor — отдельно описанные
 изменения договора, включая несовместимые. Неизвестная версия входа, политики
@@ -21,19 +21,22 @@
 
 ## Матрица форматов
 
-| Состояние, записанное…                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Пишет поверх | Примечание                                                                          |
-| ---------------------------------------------- | ------------------------ | ------------------------ | ------------ | ----------------------------------------------------------------------------------- |
-| standalone `stateVersion: 1` версией alpha.1   | да                       | да                       | да           | одна база SQLite: документ, события, локальные записи                               |
-| хост, центральная база                         | да (через адаптер)       | да (через адаптер)       | да           | данные не переносятся; новые поля необязательны                                     |
-| хост, базы компонентов                         | да (через адаптер)       | да (через адаптер)       | да           | нужна копия всех баз при остановленных writers                                      |
-| alpha.2 после штатной остановки controller     | да                       | да                       | да           | роль controller снята — нового поля в состоянии нет                                 |
-| alpha.2 с живой или брошенной ролью controller | **нет**, отказ до записи | да                       | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию |
-| alpha.4 с совместной проверкой                 | **нет**, отказ до записи | **нет**, отказ до записи | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию    |
-| неизвестная `stateVersion`                     | нет, отказ до записи     | нет, отказ до записи     | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                 |
-
-Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion`. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
+| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6    | Читает 0.1.0-alpha.7 | Пишет поверх | Примечание                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 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 и события; новые поля сохраняются → для отката всё равно копия                                     |
+| alpha.7 с новым `inspection` ревью кода                                        | не проверялось           | не проверялось           | **нет** (строгая схема) | да                   | —            | новые значения `source`, `exitCode: null`, `origins`/`context`/`excluded`; строгая схема alpha.6 их не принимает, поведение прежних версий при открытии не проверялось → откат через копию |
+| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи    | нет, отказ до записи | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                                                        |
+
+Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи) и строки alpha.7. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
 формата до записи проверяют тесты совместимости пакета
-(`tests/compatibility.test.ts`).
+<!-- repo-only -->(`tests/compatibility.test.ts`)<!-- /repo-only -->.
 
 Новые версии добавляют только необязательные поля и новые пространства
 локальных записей. Схемы состояния строгие: прежняя версия отклоняет
@@ -99,6 +102,56 @@ alpha.4 (новых полей нет).
 `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`).
+
+### alpha.7: учёт выполненных команд reviewer
+
+Формат `stateVersion: 1` прежний. `inspection` в `review.json` и evidence ревью кода получает
+новые значения и необязательные поля ([review-probes](review-probes.md#итог-inspection-что-reviewer-действительно-выполнил)):
+`source` — также `controller-probes` и `runtime-and-controller`; `commands[].exitCode` может
+быть `null`; новые `commands[].origins/status/failure/gate/note`, `context`, `total`,
+`excluded`, `excludedTotal`, `invalid`. Строки исхода в `probes.jsonl` несут `started` и
+`scope`; `review.json.probes` — `exitCode`, `started`, `scope`, `note`.
+
+Направление совместимости одностороннее: alpha.7 читает записи alpha.6 и ранее без
+пересчёта; строгая схема alpha.6 не принимает новый `source`, `exitCode: null` и новые поля,
+поэтому состояние с такими записями alpha.6 не читает. Потребителю, разбирающему
+`inspection`, нужно принять новые значения `source`, nullable `exitCode` и необязательные
+поля; признак выполнения — `mode`, а не наличие кода 0. Откат — как для alpha.6: только
+восстановлением копии состояния, сделанной до обновления.
+
 ## Перед обновлением
 
 1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
@@ -140,11 +193,11 @@ alpha.4 (новых полей нет).
 
 ## Откат
 
-| Ситуация                              | Действие                                                                                                                                                        |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Изменения исходников до выкатки       | Вернуться к проверенной паре коммитов/версий в отдельном checkout или revert-коммитами; страховочную ветку не переписывать                                      |
-| Только пакет, формат данных совместим | Остановить writers → вернуть прежнюю версию (архив или точную версию npm), зависимость и lock → `harness doctor` → возобновить                                  |
-| Новая версия уже изменила формат      | Остановить writers → восстановить согласованную копию вместе с совместимой версией пакета → сверить Git refs и артефакты (ниже); простого понижения версии мало |
+| Ситуация | Действие |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- || --------------------
+| Изменения исходников до выкатки | Вернуться к проверенной паре коммитов/версий в отдельном checkout или revert-коммитами; страховочную ветку не переписывать |
+| Только пакет, формат данных совместим | Остановить writers → вернуть прежнюю версию (архив или точную версию npm), зависимость и lock → `harness doctor` → возобновить |
+| Новая версия уже изменила формат | Остановить writers → восстановить согласованную копию вместе с совместимой версией пакета → сверить Git refs и артефакты (ниже); простого понижения версии мало |
 
 ### Сверка Git после восстановления базы
 

package/examples/README.md

@@ -19,6 +19,7 @@ npx harness validate --graph files-only/graph.json --policy files-only/policy.js
 | `one-vendor/`         | writer и reviewer одного вендора — только с явным `same-vendor-allowed` |
 | `files-only/`         | поручение, контекст и результат только файлами, без внешних сервисов    |
 | `external-connector/` | источник поручений и получатель результата через порты библиотеки       |
+| `turbo-starter/`      | pnpm/Turborepo-проект с генерацией SDK и Docker lifecycle (см. README)  |
 
 Reviewer задаётся правилом ревью явно; неявного «противоположного runtime»
 нет. При `different-vendor` (умолчание) reviewer того же вендора, что автор,