devcontour-harness 0.1.0-alpha.5 → 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

@@ -21,19 +21,21 @@
 
 ## Матрица форматов
 
-| Состояние, записанное…                         | Читает 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 | Пишет поверх | Примечание                                                                                                                                               |
+| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | -------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 — отказ до записи). Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
 формата до записи проверяют тесты совместимости пакета
-(`tests/compatibility.test.ts`).
+<!-- repo-only -->(`tests/compatibility.test.ts`)<!-- /repo-only -->.
 
 Новые версии добавляют только необязательные поля и новые пространства
 локальных записей. Схемы состояния строгие: прежняя версия отклоняет
@@ -99,6 +101,40 @@ 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`).
+
 ## Перед обновлением
 
 1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),

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 того же вендора, что автор,

package/examples/toolchains/README.md

@@ -0,0 +1,32 @@
+# Toolchains: семь вариантов target-проекта
+
+Каждый каталог — маленький target-проект с детерминированной функцией `label(n)` и поручением
+дополнять номер нулями до трёх знаков (`item-007`). Тесты проекта уже описывают новое
+поведение и защищены от записи.
+
+| Каталог        | Проект                                                            | Установка                        | Проверки                                                    |
+| -------------- | ----------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| `npm`          | Node + npm                                                        | `npm ci`                         | `npm run check`, `npm run test` (node --test, JUnit)        |
+| `pnpm`         | pnpm workspace, локальный бинарник `fx-check`                     | `pnpm install --frozen-lockfile` | `pnpm run check`, `pnpm run test` (фильтр `@fx/label`)      |
+| `turbo`        | pnpm + Turborepo 2.11.10                                          | `pnpm install --frozen-lockfile` | `turbo run check/test --filter=@fx/label`, test — `--force` |
+| `go`           | Go-модуль без package.json                                        | `go mod download`                | `go vet`, `gotestsum … -- -count=1`                         |
+| `python`       | uv-проект без package.json                                        | `uv sync --locked`               | `ruff check`, `pytest --junitxml`                           |
+| `mixed-go`     | один Git root: pnpm `frontend/` + Go `backend/` + `contract/`     | оба рецепта                      | gates с `cwd`, проверка контракта                           |
+| `mixed-python` | один Git root: pnpm `frontend/` + Python `backend/` + `contract/` | оба рецепта                      | gates с `cwd`, проверка контракта                           |
+
+Состав каталога: `repo/` — target-проект (`_gitignore` при подготовке становится
+`.gitignore`), `policy.json` — политика (`path: "repo"`), `task.json` — поручение и требования
+с `testId`, `good/` и `bad/` — файлы, которые пишет fixture writer в положительном и
+отрицательном прогоне.
+
+<!-- repo-only -->
+
+В репозитории harness (не входит в пакет). Сквозной прогон через обычный путь harness (нужны npm, pnpm, go + gotestsum, uv):
+
+```sh
+node --import tsx scripts/acceptance/t01.mjs
+```
+
+<!-- /repo-only -->
+
+Подробности — `docs/toolchains.md`.

package/examples/toolchains/go/bad/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Неверная реализация для отрицательного прогона: два знака.
+func Label(n int) string {
+	return fmt.Sprintf("item-%02d", n)
+}

package/examples/toolchains/go/good/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Label возвращает метку позиции: номер дополняется нулями до трёх знаков.
+func Label(n int) string {
+	return fmt.Sprintf("item-%03d", n)
+}

package/examples/toolchains/go/policy.json

@@ -0,0 +1,79 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": "repo",
+      "targetRef": "refs/heads/harness/accepted",
+      "prepare": [
+        {
+          "id": "install",
+          "command": ["go", "mod", "download"],
+          "timeoutMs": 600000
+        }
+      ],
+      "gates": [
+        {
+          "id": "vet",
+          "kind": "check",
+          "command": ["go", "vet", "./..."],
+          "timeoutMs": 240000
+        },
+        {
+          "id": "acceptance",
+          "kind": "test",
+          "command": ["gotestsum", "--junitfile", ".reports/junit.xml", "--", "-count=1", "./..."],
+          "timeoutMs": 240000,
+          "dependsOn": ["vet"],
+          "report": {
+            "type": "junit",
+            "path": ".reports/junit.xml"
+          }
+        }
+      ],
+      "toolchain": {
+        "tools": {
+          "gotestsum": "1.12.3"
+        }
+      },
+      "protectedPaths": [
+        ".github/",
+        ".githooks/",
+        "go.mod",
+        "go.sum",
+        "label/label_test.go",
+        "REQUIREMENTS.md"
+      ]
+    }
+  ],
+  "roles": {
+    "developer": {
+      "writer": {
+        "runtime": "claude"
+      }
+    }
+  },
+  "review": {
+    "code": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "plan": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "contract": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    }
+  },
+  "isolation": {
+    "mode": "none",
+    "domains": []
+  },
+  "maxAttempts": 2,
+  "runTimeoutMs": 900000
+}

package/examples/toolchains/go/repo/REQUIREMENTS.md

@@ -0,0 +1,9 @@
+# Requirements
+
+## REQ-LABEL-PAD
+
+label(n) pads the number to three digits: label(7) is "item-007", label(42) is "item-042".
+
+## REQ-LABEL-LONG
+
+label(n) keeps numbers longer than three digits unchanged: label(1234) is "item-1234".

package/examples/toolchains/go/repo/_gitignore

@@ -0,0 +1 @@
+.reports/

package/examples/toolchains/go/repo/go.mod

@@ -0,0 +1,5 @@
+module example.com/fxlabel
+
+go 1.24
+
+require golang.org/x/mod v0.25.0

package/examples/toolchains/go/repo/go.sum

@@ -0,0 +1,2 @@
+golang.org/x/mod v0.25.0 h1:n7a+ZbQKQA/Ysbyb0/6IbB1H/X41mKgbhfv7AfG/44w=
+golang.org/x/mod v0.25.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=

package/examples/toolchains/go/repo/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Label возвращает метку позиции.
+func Label(n int) string {
+	return fmt.Sprintf("item-%d", n)
+}

package/examples/toolchains/go/repo/label/label_test.go

@@ -0,0 +1,27 @@
+package label
+
+import "testing"
+
+func TestLabelPadsOneDigit(t *testing.T) {
+	if got := Label(7); got != "item-007" {
+		t.Fatalf("Label(7) = %q, want item-007", got)
+	}
+}
+
+func TestLabelPadsTwoDigits(t *testing.T) {
+	if got := Label(42); got != "item-042" {
+		t.Fatalf("Label(42) = %q, want item-042", got)
+	}
+}
+
+func TestLabelKeepsLong(t *testing.T) {
+	if got := Label(1234); got != "item-1234" {
+		t.Fatalf("Label(1234) = %q, want item-1234", got)
+	}
+}
+
+func TestFormatVersion(t *testing.T) {
+	if !ValidFormat() {
+		t.Fatal("format version is not semver")
+	}
+}

package/examples/toolchains/go/repo/label/version.go

@@ -0,0 +1,9 @@
+package label
+
+import "golang.org/x/mod/semver"
+
+// FormatVersion — версия формата меток (внешняя зависимость модуля проверяется go.sum).
+const FormatVersion = "v1.0.0"
+
+// ValidFormat сообщает, что версия формата — корректная semver.
+func ValidFormat() bool { return semver.IsValid(FormatVersion) }

package/examples/toolchains/go/task.json

@@ -0,0 +1,25 @@
+{
+  "title": "Pad item labels to three digits",
+  "goal": "Change label(n) in label/label.go so the number is zero-padded to three digits (item-007), keeping longer numbers unchanged.",
+  "acceptance": [
+    "label(7) is item-007 and label(42) is item-042",
+    "label(1234) is item-1234",
+    "All gates pass with fresh JUnit reports"
+  ],
+  "writeScope": ["label"],
+  "gates": ["vet", "acceptance"],
+  "requirements": [
+    {
+      "id": "REQ-LABEL-PAD",
+      "gate": "acceptance",
+      "testId": "example.com/fxlabel/label.TestLabelPadsOneDigit",
+      "scenario": "example.com/fxlabel/label.TestLabelPadsOneDigit runs and passes on the accepted SHA"
+    },
+    {
+      "id": "REQ-LABEL-LONG",
+      "gate": "acceptance",
+      "testId": "example.com/fxlabel/label.TestLabelKeepsLong",
+      "scenario": "example.com/fxlabel/label.TestLabelKeepsLong runs and passes on the accepted SHA"
+    }
+  ]
+}

package/examples/toolchains/mixed-go/bad/backend/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Неверная реализация для отрицательного прогона: два знака.
+func Label(n int) string {
+	return fmt.Sprintf("item-%02d", n)
+}

package/examples/toolchains/mixed-go/bad/frontend/src/label.js

@@ -0,0 +1,4 @@
+// Метка позиции заказа: номер дополняется нулями до трёх знаков.
+export function label(n) {
+  return `item-${String(n).padStart(3, '0')}`;
+}