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

package/docs/architecture.md

@@ -0,0 +1,496 @@
+# Архитектура devcontour-harness
+
+Harness — headless-движок исполнения инженерных поручений. Он получает
+согласованный граф поручений, выдаёт попытки исполнителю в изолированном
+worktree, прогоняет обязательные проверки, получает независимое ревью,
+интегрирует результат с текущей принятой веткой, повторяет проверки и ревью на
+integration SHA и продвигает целевую ветку только compare-and-swap. Итог —
+машинный результат с SHA, доказательствами и ограничениями.
+
+Harness не хранит продуктовых задач, памяти, досок или релизов и не содержит
+UI. Он используется двумя способами одного и того же движка:
+
+1. **Самостоятельно** — библиотека или CLI, файловое поручение и контекст,
+   локальное состояние запусков, результат в JSON. Агент пользователя
+   подготавливает проект (`init`), составляет план (`plan-request`,
+   `plan-check`) и объясняет остановки (`explain`) без ручных служебных JSON.
+2. **Внутри хоста** (например, DevContour) — хост подключает свои адаптеры
+   хранения, источника поручений и получателя результата; правила исполнения и
+   технической приёмки остаются в пакете.
+
+## Процесс
+
+```text
+Постановка и закреплённый контекст
+                 |
+                 v
+План / контракты -> отдельное техническое ревью (digest)
+                 |
+                 v
+Согласованный граф -> claim -> реализация в worktree
+                 |
+                 v
+Candidate SHA -> обязательные gates -> независимое ревью
+                 |
+                 v
+Интеграция с текущей принятой веткой
+                 |
+                 v
+Integration SHA -> gates и потребители -> независимое ревью
+                 |
+                 v
+Проверка владения, входов и evidence -> CAS target ref -> принятие
+                 |
+                 v
+RunResult (SHA, evidence, ограничения) -> ResultSink
+
+Замечания -> ограниченная следующая попытка
+Неустранимый отказ / лимит / отмена -> остановка с причиной
+```
+
+## Модули
+
+| Модуль         | Ответственность                                                                       |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `contracts`    | Версионируемые входы/выходы, схемы, коды ошибок, события, описания портов             |
+| `engine`       | Переходы исполнения, DAG, владение, техническое согласование и приёмка, повторы       |
+| `agents`       | Адаптеры Codex/Claude, роли, свежие сессии, выбор reviewer, нормализация ответов      |
+| `environment`  | Подготовка среды, снимки зависимостей, sandbox, инструменты, ресурсы, cleanup         |
+| `verification` | Gates, ревью и probes, evidence, корпус, свойства, совместная проверка                |
+| `storage`      | Транзакционный порт `ExecutionStore` и самостоятельная SQLite-реализация              |
+| `connectors`   | `WorkSource`, `ContextSource`, `ResultSink`; встроенные файловые реализации           |
+| `control`      | Команды и чтение состояния/событий для библиотеки и CLI                               |
+| `profiles`     | Разрешение профилей стека (только чтение манифестов), закрепление, сборка политики    |
+| `toolchains`   | Требования профиля к инструментам: манифесты, рецепты, проверка версий                |
+| `integrations` | Опциональные подключения Relay v1/v2 и памяти; по умолчанию выключены                 |
+| `testing`      | Контрактные проверки для собственных реализаций `ExecutionStore`                      |
+| `init`         | `harness init`: обнаружение проверок проекта, политика, план безопасной записи файлов |
+| `setup`        | Безопасная подготовка файлов: проверка назначения, план и create-only запись          |
+| `planning`     | Запрос планирования и факты проекта, проверка draft, сборка `WorkGraph`               |
+| `explain`      | Объяснение остановки по состоянию: причина, действующая сторона, следующее действие   |
+| `projections`  | Чистые проекции для отображения: корни цепочек, прогресс, остановка очереди, усечение |
+| `catalog`      | Каталог агентских операций, байтовые пределы и постраничная выдача ответов            |
+
+Таблица перечисляет каталоги `src/`. Git-операции — worktrees, snapshots,
+проверка области, candidate/integration, CAS и recovery — отдельного каталога
+не образуют: они в `engine` (`runner.ts`, `joint-runner.ts`), `control`
+(`base-move.ts`) и `verification`. Поставляемые skills лежат в корневом
+каталоге пакета `skills/`, шаблоны — в `templates/`; исполняемые гарантии
+остаются в движке.
+
+Модули `setup`, `planning`, `explain`, `projections`, `catalog` и разрешение
+профилей с `layerSchema` — общие операции и для самостоятельного проекта, и для
+хоста. Хост вызывает их из пакета и не держит своих копий этих алгоритмов; у
+него остаются продуктовые правила, согласования, память, UI и своё хранилище.
+Подробно — [самостоятельный проект](standalone.md) и [договоры](contracts.md).
+
+`contracts` — лист графа зависимостей: он не импортирует других модулей,
+процессов, файловой системы и сети. Линтер проверяет это правило как ошибку.
+
+## Направление зависимостей
+
+```text
+Файлы ---------> WorkSource / ContextSource ---+
+                                              |
+Хост ----------> его адаптеры ----------------> Harness
+                                              |
+Внешняя память -> внешние адаптеры -----------+
+                                              |
+                          +-------------------+-------------------+
+                          v                   v                   v
+                   Runtime adapters      Git / проверки     ExecutionStore
+                          |                                       |
+                          +-----------> RunResult / events <------+
+                                              |
+                                              v
+                                          ResultSink
+```
+
+Хост зависит от harness; harness не зависит от хоста. Обратные импорты,
+чтение соседнего checkout и загрузка его модулей через subprocess запрещены;
+пакет работает, когда исходников хоста на машине нет. UI-зависимости не входят в
+runtime-граф пакета.
+
+## Одна транзакция исполнения
+
+Решения движка — claim, продление и проверка владения, запись evidence,
+приёмка — выполняются внутри одной синхронной транзакции `ExecutionStore`.
+Внутри неё:
+
+1. движок читает нейтральные записи (`WorkState`, `AttemptState`,
+   `ControlState`) через `ExecutionView`;
+2. хост добавляет свои условия через `HostGuards` — они могут только запретить;
+3. основания (digest постановки, области и политики) даёт `BasisProvider`;
+4. изменения записываются `put*`, события — `emit`;
+5. при приёмке до фиксации выполняется CAS `git update-ref <ref> <new> <old>`;
+   отказ CAS откатывает транзакцию.
+
+**Standalone.** `ExecutionStore` — встроенная SQLite (`node:sqlite`,
+`BEGIN IMMEDIATE`): документ нейтрального состояния, таблица событий и
+локальные записи (учёт вызовов, idempotency-ключи, receipts доставки) в одной
+базе. Других копий изменяемого состояния исполнения нет.
+
+**Внутри хоста.** Адаптер `ExecutionStore` работает через существующую
+транзакцию хоста и отображает его записи в нейтральные структуры. Хост не
+заводит вторую базу с независимо изменяемыми статусами и попытками; движок не
+переносит его исторические записи. Если хост хранит состояние в нескольких
+базах (например, по компонентам), атомарность обеспечивает его транзакция над
+ними всеми.
+
+Падение процесса между `update-ref` и фиксацией разбирает recovery: попытка
+принимается только по сохранённому integration SHA, который уже в target ref,
+и только с полными актуальными evidence; повтор recovery не создаёт второго
+принятия.
+
+## Технические гарантии
+
+- **Fencing.** Каждая операция попытки предъявляет fencing-токен; запоздалый
+  ответ прежнего владельца, истёкший lease или чужой токен ничего не пишет.
+  Токен не попадает в события, результат и логи.
+- **Один controller.** Очередь ведёт один действующий controller с lease;
+  второй не выдаёт попыток.
+- **Применённая политика у каждого вызова.** Начало любого учитываемого вызова
+  runtime (writer, ревью кода, плана, контракта, разбор) в той же транзакции
+  сверяет политику процесса с применённой: процесс, чью политику сменили
+  (например, понизили бюджет), новых вызовов не начинает (`APPROVAL_STALE`).
+- **Применение политики хостом.** Запрос операции применяется только после
+  окончания работ под прежней политикой — попыток, совместных проверок,
+  заданий и работ хоста (`HostGuards.busy`, у DevContour — поставка и
+  preview). Хост, не сумевший прочитать ожидаемую политику, записывает отказ
+  с причиной (`rejectReconfigure`); повтор операции его сбрасывает. Хост с
+  `recordPolicyOnLead: false` записывает применённую политику сам
+  (`recordPolicy`) — только действующим controller.
+- **Совместная проверка хоста.** Хост может начать проверку в своей
+  транзакции (с продуктовыми условиями) и передать её `JointRunner.run`;
+  каталог, окружение gates и подготовку задаёт хост. Digest политики и
+  основание считаются формулами хоста, если он их задаёт
+  (`BasisProvider.jointPolicyDigest/jointSpecDigest`); продуктовые условия
+  каждой записи — `HostGuards.joint`. `jointResult(workIds, id)` оценивает
+  указанную проверку.
+- **Расход ревью плана.** Вызов о графе закрепляет за расходом группу и
+  поручения из входного графа — и до его регистрации; повтор после
+  исчерпания бюджета поручения или группы отклоняется до вызова.
+- **Контекст ревью плана.** Reviewer плана получает закреплённый снимок
+  контекста (содержимое и digest); без нужного источника или с испорченным
+  снимком — отказ до вызова. Раунд подтверждает граф только с тем же снимком:
+  другой контекст при том же графе — новый раунд.
+- **Удержания переживают редакции.** Новая редакция источника сохраняет
+  удержание операции; снимает его только владелец (release или передача).
+- **Незавершённая очистка.** Если teardown окружения попытки или проверки
+  потребителя не завершился, её рабочие деревья и снимки зависимостей
+  остаются и записываются в `cleanup-pending.json`; ошибки обычного удаления
+  записываются туда же. `Harness.cleanup(runId)` повторяет teardown по
+  сохранённым `environment.json` и затем убирает деревья, повторный вызов —
+  `nothing-pending`.
+- **Покрытие gates.** `uncoveredGates` засчитывает только evidence попыток под
+  текущим основанием политики: тот же ID gate с другой командой — другая
+  проверка.
+- **Область записи.** Изменения вне `writeScope`, защищённых путей и
+  закреплённого контекста отклоняют попытку до интеграции.
+- **Gates.** Тестовый gate принимается по свежему непустому отчёту без
+  failures/errors/skips на точном SHA; exit 0 и слово PASS в выводе не заменяют
+  отчёт. Gate или reviewer, изменивший дерево или HEAD, проверку не проходит.
+- **Независимое ревью.** Reviewer — отдельная роль и свежая сессия; он
+  получает исходные критерии, согласованные контракты, закреплённый контекст,
+  diff и evidence, которые controller записал о проверяемом SHA, прежние
+  находки, но не историю рассуждений, отчёт и ID сессии writer. Права reviewer
+  только на чтение; evidence ревью пишет controller по ответу reviewer, writer
+  такого права не имеет. Невалидный ответ,
+  `approved` при блокирующей находке, таймаут — отказ, не самооценка writer.
+- **Политика вендоров.** Reviewer задан явно для каждого вида ревью (код,
+  план, контракт). По умолчанию reviewer того же вендора, что и writer,
+  отклоняется; режим одного вендора включается явно (`same-vendor-allowed`) и
+  сохраняет все остальные условия приёмки. Неявного выбора «противоположного
+  runtime» нет ни в ревью, ни в разборе ведущего (его ведёт runtime автора).
+- **CAS приёмки.** `git update-ref` target ref исполняется внутри транзакции
+  приёмки без hooks репозитория (`core.hooksPath=/dev/null`) и с конечным
+  пределом времени; зависший или отклонённый hook не держит блокировку и не
+  срывает приёмку.
+- **Согласование привязано к digest.** Смена постановки, состава графа,
+  области проверок или политики требует нового согласования. Публичного метода
+  «передать PASS и принять» нет.
+- **Внешняя предпосылка** считается выполненной только по результату движка
+  либо доверенному receipt с доступным result SHA; отметка `done` без SHA не
+  доказательство. Файловый коннектор по умолчанию не доверяет внешним receipts.
+- **Ограниченное восстановление.** В режиме `agent` работа над графом —
+  задание технической очереди (`workflow-jobs`): стадия (согласование,
+  исполнение, завершено) сохраняется и переживает рестарт; владелец задания
+  fenced. Упавшее поручение повторяется только по записанному классу отказа:
+  в пределах повторов одинакового отпечатка для класса, попыток поручения
+  (`maxAttempts`) и бюджета восстановлений задания (`repairBudget`). Решение и
+  списание бюджета — одна транзакция с повтором. Отказ провайдера, отмена,
+  неизвестный класс и устаревшая база — остановка с причиной. Восстановление
+  снимает только свою причину паузы; паузу человека не снимает. Режим
+  `operator` автоматических повторов не делает.
+- **Переиспользование кандидата.** После отказа окружения или по времени,
+  когда кандидат уже был, повтор берёт его вместо новой реализации, только
+  если совпадают все основания: постановка, контракты, политика, runtime и
+  модель, база, контекст, зависимости, версия движка и версия корпуса. Gates и
+  оба ревью исполняются заново; взятый кандидат проходит ту же проверку
+  области. Попытка, оборванная до кандидата, оставляет черновик в области
+  записи; отклонённый кандидат — отправная точка следующей попытки; ни то, ни
+  другое не заменяет проверок.
+- **Бюджеты.** Каждый вызов модели (writer, ревью кода, плана и контракта)
+  идёт через учёт: в одной транзакции с регистрацией идущего вызова
+  проверяются бюджеты поручения, его групп и общий; превышенный или
+  неопределённый — отказ класса `budget` до вызова, без записи. Расход
+  считается по сохранённым записям вызовов, а не по счётчикам попыток: сброс
+  попыток, повтор и перезапуск его не уменьшают; ошибочные, идущие и
+  прерванные вызовы входят в расход. Неизвестная стоимость не становится нулём:
+  денежный бюджет тогда не определён, и `onUnknown` решает, останавливаться
+  ли. Атрибуция (поручение, группа, поручения группы) закрепляется при вызове:
+  перенос поручения в другую группу хоста расход не переносит. Тариф
+  закрепляется на старте вызова и выбирается по модели, о которой сообщил
+  runtime. Вызов умершего процесса закрывается как прерванный; владелец,
+  которого нельзя ни подтвердить, ни опровергнуть, живым не считается, а его
+  вызов не закрывается. Время — по монотонным часам; откат системных часов
+  его не уменьшает, а несравнимые метки дают неизвестное время, а не ноль.
+  Готовое поручение под исчерпанным бюджетом не выдаётся и несёт причину.
+- **Область доказательства.** Группы gates (`@имя`) раскрываются в явный
+  список один раз, без циклов и членов вне профиля; список закрепляется за
+  попыткой. Без области — весь профиль репозитория. Область замкнута по
+  `dependsOn` gates и содержит test gate.
+- **Потребители.** Поручение явно называет потребителей — репозитории,
+  зависящие от его репозитория, — и их gates. Потребитель проверяется на
+  integration в своём рабочем дереве на голове своей целевой ветки: компонент
+  поручения подставлен интегрированным результатом, прочие зависимости
+  потребителя собраны против него; действуют lifecycle, prepare и cleanup
+  потребителя, ресурсы его gates резервируются на всю попытку. Evidence
+  потребителя несёт его репозиторий и не закрывает ни собственные gates, ни
+  требования поручения. Приёмка требует PASS каждого gate потребителя на
+  integration SHA и записи, что проверено (голова потребителя, снимки его
+  зависимостей с интегрированным результатом, их свежесть).
+- **Договор проверки и генеративные gates.** Контракт может нести договор
+  проверки (`checks`): обязательства по property ID с областью входов,
+  правилами ответа, независимым способом проверки и минимальным покрытием, и
+  закреплённые файлы checker/oracle (`artifacts`, Git blob). Неполный договор
+  и файлы, не совпадающие с целевой веткой, отклоняются до вызова reviewer.
+  Поручение включает механизм полем `properties`; свойства, которых нет в его
+  договорах или которые исполняет не генеративный gate, не согласуются.
+  Генеративный gate получает seed controller (`DEVCONTOUR_SEED`, свой у
+  попытки, фазы и gate), селектор свойств и закреплённый корпус; отчёт
+  свойств читается при любом исходе из каталога вне worktree. Gate проходит,
+  только если отчёт подтверждает манифест поручения: каждое свойство, его
+  минимальную выборку по семействам и все случаи корпуса (свидетельство
+  исходов, а не счёт); зелёный JUnit и код 0 этого не заменяют. Закреплённые
+  файлы контракта — защищённые пути попытки. Приёмка (`finish`, а через него
+  recovery) повторно требует для каждого gate объявленных свойств решающую
+  запись обеих фаз с манифестом этого договора и исполненным корпусом
+  закреплённой версии — независимо от состава `requiredGates`; сохранённое
+  evidence без манифеста, с прежним уровнем или заниженным корпусом не
+  принимается. Те же правила проверяет получатель переносимого результата
+  (`resultProblems`): результат прежнего формата у поручения без договора
+  проверки читается на прежнем уровне, у поручения с договором — отклоняется.
+- **Эксперимент выполнимости (spike).** Тяжёлое обязательство ссылается на
+  ограниченный эксперимент по ID и digest. Эксперимент исполняет команду на
+  закреплённом SHA в отдельном worktree под изоляцией gates, для каждого
+  размера — с пределом времени; после таймаута большие размеры не
+  запускаются. Таймаут — `inconclusive`: не доказательство невыполнимости и
+  не основание ослаблять обязательство. Неизвестный эксперимент или другой
+  digest — отказ ревью контракта до вызова модели; reviewer получает
+  фактический результат эксперимента.
+- **Самопроверка исполнителя.** Writer поручения со свойствами получает
+  команду самопроверки: закреплённый checker, полный корпус версии попытки
+  (а не только случаи подсказки), seed и селектор свойств — на рабочем
+  дереве. Это диагностика: gates на commit SHA исполняются всегда, и без
+  самопроверки отказы те же.
+- **Корпус подтверждённых случаев.** Пример reviewer или ведущего — гипотеза.
+  Controller запускает закреплённый checker в режиме одного случая дважды на
+  дефектном SHA и требует воспроизводимого расхождения с эталоном; ожиданием
+  становится ответ эталона. Команда из воспроизведения не исполняется.
+  Подтверждённый случай — новая неизменяемая версия корпуса; поручение
+  принимает её отдельной операцией: посередине попытки выдача удерживается и
+  принятие ждёт её конца, в режиме `operator` — ручного подтверждения.
+  Принятое поручение версию не меняет. Повтор ключа подтверждения возвращает
+  прежнее решение. Версия проверок (`effectiveChecks`: постановка, контракты,
+  политика, корпус) закрепляется при выдаче; приёмка, recovery и reuse под
+  другой версией отклоняются. Корпус принадлежит нормативному основанию договора
+  (закреплённые файлы, gate, область входов, правила ответа, способ
+  проверки), а не ID контракта: новая редакция того же ID с другим
+  основанием получает отдельный корпус, привязка поручения к прежнему
+  снимается новой редакцией графа, принятая история прежнего корпуса
+  остаётся. Изменение постороннего контракта или текста без смены основания
+  привязку сохраняет.
+- **Эпизод по свойству.** Два последовательных содержательных отказа (gate
+  или ревью) одного поручения по одному объявленному свойству запрещают
+  третью автоматическую выдачу до разбора. Отказ окружения, провайдера и по
+  времени счёт не увеличивает и не обнуляет; необъявленное свойство эпизод не
+  открывает. Автоматический разбор ведущего — один на эпизод и учитывается
+  вместе с бюджетом восстановлений до вызова модели; разрешено добавить
+  подтверждённые случаи или один повтор с новой гипотезой, прочие действия —
+  предложение для обычного ревью или решение человека. Эпизод закрывает
+  проверенное прохождение свойства, приёмка или согласованное новое
+  основание.
+- **Зависимости.** Снимок зависимостей репозитория (рабочие деревья целевых
+  веток, `dependencyBuild`, digests `dependencyArtifacts`) закрепляется до
+  реализации; изменение снимка writer-ом, gate или reviewer — отказ. Свежесть
+  снимка на момент окончания записывается в попытке и результате; сдвиг ветки
+  зависимости приёмку не запрещает — сочетание версий проверяет совместная
+  проверка.
+- **Совместная проверка.** Набор принятых поручений нескольких репозиториев
+  проверяется вместе gates уровня workspace (`workspaceGates`) на текущих
+  target ref: результат каждого поручения обязан входить в них; manifest
+  фиксирует SHA и tree каждого репозитория политики. Gates исполняются в той
+  же песочнице, что и проверки поручений, и в снимках компонентов; gate,
+  изменивший manifest, уже снятый artifact или исходники любого компонента,
+  проверку не проходит. Пока идёт проверка, попытки не выдаются, а она сама
+  не начинается при идущих попытках. Результат привязан к manifest, к
+  политике совместной проверки и к основанию — постановкам, статусам и
+  результатам поручений набора; смена любого из них делает прежний результат
+  неактуальным (`jointResult`), а сдвиг target ref после проверки виден как
+  свежесть manifest. Атомарного продвижения нескольких Git-репозиториев нет;
+  продуктовое принятие комбинации решает хост. В режиме `affected` при
+  принятой хостом прежней проверке под той же политикой исполняются только
+  изменённые компоненты, их транзитивные потребители и prerequisites их
+  gates.
+- **Применённая политика.** В хранилище записана применённая политика
+  (digest загруженной политики целиком и поколение). Процесс, чья политика с
+  ней не совпадает, не выдаёт, не согласует, не принимает и не ведёт
+  совместную проверку. Записать свою политику применённой (перезапуск с
+  другой политикой) процесс может, только если нет живого чужого controller,
+  его политика не менялась в памяти, её файл содержит те же байты по той же
+  цели и после запуска процесса никто не применил другую — поколения
+  считаются по записям, не по часам. Операция меняет политику работающего
+  контура запросом с ожидаемым digest: новые выдачи и совместные проверки
+  удержаны, пока запрос не применён; применяет его процесс ровно с ожидаемой
+  политикой, когда работ под прежней не осталось (запись с истёкшим сроком
+  их не держит); другая политика — отказ с обоими digest. Пауза человека и
+  штатной остановки переживает операцию. Попытка, выданная под прежней
+  политикой, под новой не принимается. Пределы бюджетов и тарифы в основание
+  согласования и fencing не входят (`executionDigest`): поднятый предел
+  действует без нового согласования.
+- **Удержания операций.** Операция удерживает поручения от выдачи; удержание
+  другой операции — конфликт; снимает и передаёт его только своя операция,
+  передача — без окна выдачи. Владение операцией проверяется в той же
+  транзакции (`fence`): утративший его ничего не пишет. Перенос базы
+  сдвигает target ref CAS-ом внутри транзакции проверки владения, без hooks
+  репозитория и с конечным пределом времени Git.
+- **Изоляция.** Режим `os` ограничивает процессы writer, reviewer и gates; если
+  обязательный sandbox недоступен — отказ, а не тихое выполнение без изоляции.
+  Режим `none` выбирается только явно.
+- **Проверки reviewer.** Reviewer кода, которому политика и так даёт запуск
+  команд (codex с shell, claude с Bash в профиле), получает MCP-сервер
+  `devcontour_probe` с инструментом `run_check`; reviewer только для чтения и
+  writer его не получают. Команда (argv, без shell) исполняется тем же
+  исполнителем, что и gates: песочница режима `os`, исходники только для
+  чтения, остановка потомков. Срок задаёт controller: предел на команду, общий
+  бюджет проверок с атомарным резервированием (одновременные вызовы его не
+  превышают) и резерв времени на заключение (`reviewProbes`, не меньше пятой
+  части срока прогона). Таймаут и исчерпанный бюджет — типизированный
+  результат, а не зависание ревью. Аргументы и вывод маскируются; значения
+  переменных окружения передаются серверу по имени и на диск не пишутся.
+  Запуски записываются в журнал controller (`probes.jsonl`) и попадают в
+  `review.json`; воспроизведение находки «наблюдено» только по единственному
+  состоявшемуся запуску, на который сослался reviewer (`reproduction.run`),
+  и команда в записи — та, что запускалась. Команда из текста находки не
+  исполняется.
+- **Воспроизведения находок.** Находки ревью кода с воспроизводимым входом
+  записываются в реестр поручения (`reproductions`) уже замаскированными:
+  одно свойство на одном входе — одна запись, повтор добавляет прогон;
+  подтверждение запуском не отменяется последующей гипотезой; реестр
+  ограничен 500 записями на поручение. Следующая попытка — writer и
+  reviewer — получает последние 20 входов с ожиданием, наблюдением и командой.
+  Это диагностика: gate не расширяет и корпусом не становится без
+  подтверждения эталоном; обязательный корпус от ограничения реестра не
+  зависит.
+- **Контекст плана и согласование.** Снимок контекста хранится по digest, а
+  действующим становится только вместе с согласованием графа
+  (`approval.context`). Пока новый снимок на ревью, после его отклонения,
+  отказа runtime reviewer, в режиме operator до `approve` и после
+  перезапуска исполняется прежний согласованный снимок. Попытка, выданная на
+  снимке, отличном от согласованного к моменту приёмки, не принимается.
+- **Предмет вызова.** Вызов модели о графе засчитывается группе и её
+  участникам, о контракте — общему бюджету: явный вид предмета
+  (`subjectKind`) важнее совпадения строки ID с поручением. Прежняя запись
+  без вида, но с закреплённой при вызове группой и без поручения — вызов о
+  группе: закрепление (`pinLegacyCalls`) дописывает ей состав, а не
+  поручение с совпавшим ID; уже закреплённый `workId` не меняется.
+- **Эксперимент и маска.** Запись эксперимента выполнимости (команда, вопрос,
+  пределы) маскируется известными значениями окружения до digest и записи;
+  недостающий секрет — отказ до worktree. Ошибка запуска возвращается в
+  безопасной форме: маскированы сообщение, стек, причина и все поля ошибки
+  процесса (`path`, `spawnargs` и др.), класс и код сохранены.
+
+## Профили, skills и шаблоны
+
+Встроенные профили (`profiles/`), skills (`skills/harness/SKILL.md` — работа
+с поручениями, `skills/harness-setup/SKILL.md` — установка, первая настройка
+и обновление версии) и шаблоны (`templates/`: политика, граф, инструкция
+агентам репозитория) входят в пакет. Skills и шаблоны только объясняют использование: движок, runner и проверки их
+не читают, и удаление каталога skills не отключает ни gates, ни ревью, ни
+область записи, ни fencing — это проверяет smoke установленного архива.
+Профиль — вход для сборки политики, а не исполняемый объект: разрешение не
+запускает команд проекта, и после сборки политика несёт gates сама.
+
+## Доставка результата
+
+`execution accepted` и `delivery pending/failed` — разные состояния. Принятый
+код не откатывается из-за недоступного получателя. Повтор доставки идёт с тем же
+ключом и не вызывает моделей, интеграции или второй записи. Если в источнике
+уже более новая редакция поручения, получатель отвечает конфликтом, а старый
+результат её не закрывает. Коннекторы не могут менять политику, выдавать lease,
+ослаблять gates или ставить технический PASS — у портов нет таких операций.
+
+## Fixture-режим
+
+Runtime `fixture` возвращает управляемые ответы для тестов и демо; это не
+живая модель, и он не выбирается при отсутствии учётных данных. Тесты
+адаптеров Codex/Claude проходят настоящий subprocess-протокол через fixture
+executable. Live smoke — отдельный opt-in с явно заданными моделями и
+лимитами. Fixture-проверки доказывают механику процесса, а не качество модели.
+
+## Границы доверия участников
+
+```text
+ ┌──────────────────── доверенная зона: controller ─────────────────────┐
+ │ движок, состояние (SQLite), токены владения, политика, CAS target ref │
+ │ решает: выдачу, приёмку, повторы, бюджеты, доставку                   │
+ └───────────────▲───────────────────────────────▲──────────────────────┘
+                 │ только ответы по схеме        │ только записи evidence,
+                 │                               │ которые пишет controller
+ ┌───────────────┴─────────────┐   ┌─────────────┴──────────────────────┐
+ │ writer: свой worktree,      │   │ gates: команды политики в песочнице │
+ │ запись только в области     │   │ отчёт JUnit/свойств читает harness  │
+ ├─────────────────────────────┤   ├────────────────────────────────────┤
+ │ reviewer: свежая сессия,    │   │ коннекторы: источник, контекст,     │
+ │ только чтение, свой SHA     │   │ получатель — без права на политику, │
+ └─────────────────────────────┘   │ lease или PASS                      │
+                                   └────────────────────────────────────┘
+```
+
+| Участник  | Что может                                                                | Чего не может                                                                                |
+| --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| Writer    | Менять файлы своей области в своём worktree                              | Менять защищённые и контекстные файлы, HEAD, state controller; объявить свою работу принятой |
+| Reviewer  | Читать дерево, diff, evidence; запускать проверочные команды через probe | Править дерево или HEAD; продолжать сессию writer; одобрить при блокирующей находке          |
+| Gate      | Выполнить команду политики и записать отчёт                              | Изменить проверяемый код (изменённое дерево делает проверку недействительной)                |
+| Коннектор | Отдать граф, контекст; принять результат                                 | Менять политику, выдавать lease, ослаблять gates, ставить технический PASS                   |
+| Оператор  | Согласовать граф (`operator`), пауза, отмена, повтор, сброс              | Принять поручение без gates и ревью — такой операции нет                                     |
+
+## Что гарантируется
+
+- **Владение.** Каждая попытка пишет только своим токеном; поздний ответ
+  прежнего владельца, истёкший lease и второй controller ничего не меняют.
+- **Точные SHA.** PASS gate и ревью относится к конкретному candidate или
+  integration SHA; доказательство другой фазы или другого SHA не засчитывается.
+- **Атомарная приёмка.** Продвижение target ref — compare-and-swap внутри
+  транзакции приёмки. Чужой коммит в target ref не теряется: попытка начнётся
+  от новой базы. Падение между update-ref и записью принятия восстанавливается
+  проверкой сохранённых evidence, а не выдумыванием PASS.
+- **Входы.** Согласование привязано к digest постановки, контрактов,
+  контекста и политики; их изменение делает согласование и попытку устаревшими.
+- **Изоляция.** Режим `os` реально ограничивает процессы writer, reviewer и
+  gates; без механизма песочницы команда не запускается — тихого перехода к
+  запуску без неё нет. Зависшие процессы останавливаются вместе с потомками.
+- **Секреты.** Значения секретов маскируются во всём сохраняемом: логах,
+  артефактах ревью, evidence, событиях и результате.
+- **Бюджеты.** Проверяются до вызова модели в той же транзакции, что и запись
+  вызова; неизвестная стоимость не считается нулём.
+- **Независимость ревью.** По умолчанию reviewer другого вендора; один вендор
+  только явным правилом, и даже тогда — отдельная роль и свежая сессия.
+
+## Чего harness не делает
+
+- Не оценивает качество модели: fixture-тесты проверяют механику процесса.
+- Не обеспечивает атомарность продвижения нескольких репозиториев сразу:
+  совместная проверка удостоверяет комбинацию SHA, принятие решает хост.
+- Не хранит продуктовых задач, досок, памяти и UI — это дело хоста.

package/docs/compatibility-versions.md

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