devcontour-harness 0.1.0-alpha.13 → 0.1.0-alpha.18

package/README.md

@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
 интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
 и доказательствами.
 
-> Статус: `0.1.0-alpha.13` — предварительный выпуск (alpha). Договоры
+> Статус: `0.1.0-alpha.18` — предварительный выпуск (alpha). Договоры
 > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
 > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
 > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
 Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
 
 ```sh
-npm install --save-exact devcontour-harness@0.1.0-alpha.13   # точная версия
+npm install --save-exact devcontour-harness@0.1.0-alpha.18   # точная версия
 # или: npm install --save-exact devcontour-harness@alpha     # текущая alpha
 npx harness --version
 ```
@@ -123,6 +123,52 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
 `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
 Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
 
+## Выпуск 0.1.0-alpha.18
+
+`runGatesAt` исполняет gates с предпосылками профиля: явный `dependsOn` или,
+в профиле без него, более ранние check gates (установка); общий с попыткой
+порядок `orderedScope`; все провалы — сразу; `dependsOn: []` — без
+предпосылок. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.18.md).
+
+## Выпуск 0.1.0-alpha.17
+
+Меньше слепых повторов: reviewer называет класс входов, два отказа ревью по
+одному свойству и классу — пробел приёмки с остановкой; отказы окружения не
+тратят попытки (свой предел), штатная остановка возвращает работу в очередь,
+`completed: false` повторяется с черновика; пустой результат принимается
+только с механическим основанием (иначе `needs-lead`), `runGatesAt` проверяет
+gates на закреплённом SHA; стоимость вызова учитывается по всему потоку. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.17.md).
+
+## Выпуск 0.1.0-alpha.16
+
+Отказ по файлу эталонного набора — только по строковому литералу, без ложных
+отказов на комментариях и похожих именах; reviewer контракта видит минимумы
+семейств. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.16.md);
+alpha.14 и alpha.15 — локальные выпуски, в npm не публиковались.
+
+## Выпуск 0.1.0-alpha.15
+
+Эталонные наборы защищены от подгонки. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.15.md); alpha.14 — локальный
+выпуск, в npm не публиковался.
+
+- Writer и reviewer кода знают файлы эталонных наборов; кандидат, чей
+  изменённый файл называет файл набора, отклоняется до gates.
+- `crossChecks[].artifacts`: закреплённый скрипт или журнал сверки эталона.
+- Обязательство, которое поручение выбрать не может, отклоняется сразу; ID
+  testcase node:test (`test.<имя>`) описан и подсказан в отказе.
+
+## Выпуск 0.1.0-alpha.14
+
+Проверка по закреплённым эталонным наборам. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.14.md).
+
+- `verification: "reference"` в договоре проверки: обещание проверяется
+  наборами ответов независимого эталона, закреплёнными артефактами контракта;
+  gate без генератора подтверждает отчётом свою долю входов и семейств.
+- `obligations[].gates`: обязательство исполняют несколько gates.
+- Reviewer контракта видит пределы наборов (`gaps`) и сверку эталона.
+
 ## Выпуск 0.1.0-alpha.13
 
 Controller mode для задач Relay и установка без лишних вопросов. Подробно —

package/docs/architecture.md

@@ -185,6 +185,49 @@ runtime-граф пакета.
 - **Покрытие gates.** `uncoveredGates` засчитывает только evidence попыток под
   текущим основанием политики: тот же ID gate с другой командой — другая
   проверка.
+- **Пауза по классу отказа.** Отказ класса с `blocksQueue`
+  (`provider-auth`, `environment`) в той же транзакции ставит паузу
+  `runtime` и добавляет класс в `pauseFailures`: новых выдач нет ни одной
+  задаче. Отказ окружения до кандидата (`blocked`) попытку не засчитывает.
+  Снимает паузу `clearFailure([класс])` — его вызывает восстановление,
+  назначившее повтор (у DevContour — цикл board workflow, той же транзакцией,
+  что повтор), — или `resume` человека; выдача возвращается, когда в списке не
+  осталось классов. Поэтому разовый отказ окружения под циклом восстановления
+  останавливает выдачу только до его следующего шага, а без цикла пауза стоит
+  до решения человека. Пауза человека этим не снимается.
+- **Gates на SHA вне попытки.** `runGatesAt` исполняет названные gates
+  компонента на закреплённом SHA так же, как integration поручения:
+  отдельное рабочее дерево, снимки зависимостей, ресурсы, lifecycle и
+  prepare, окружение фазы `integration`, песочница и `runGate`. Область —
+  названные gates и предпосылки каждого (`standaloneScope`), порядок — тот же
+  `orderedScope`, что у попытки. Предпосылки (`gatePrerequisites`): у gate с
+  объявленным `dependsOn` (в том числе пустым — режим графа) — замыкание по
+  `dependsOn`; у gate без поля `dependsOn` (профиль в режиме порядка массива)
+  — все более ранние gates вида `check` с их предпосылками: установка,
+  сборка, статические проверки. Более ранние test gates не добавляются;
+  каждый gate посещается один раз. Задаче эти предпосылки называть
+  по-прежнему приходится явно: её область исполняется как записана. Провал
+  gate не останавливает проверку. Пропускается только gate, чья явная
+  предпосылка (`dependsOn`) не прошла; провал неявной (раннего check gate)
+  тесты не пропускает — названы оба (`failures`). Evidence (`test`,
+  `integration`, этот SHA) пишется через запись хоста до следующего gate;
+  дерево обязано остаться на SHA без изменений.
+- **Пустой результат.** Исполнитель, не изменивший ни файла, не получает
+  отказ сразу: кандидат — сама база (без коммита), gates поручения идут на
+  ней, а reviewer обеих фаз получает схему ответа с обязательным
+  `alreadySatisfied` (gates области задачи — хотя бы один test gate и все
+  проверки договоров поручения — и основание). Подтверждения reviewer мало:
+  нужно механическое основание, которое находит controller
+  (`alreadySatisfiedVerdict`): договор проверки поручения, все gates которого
+  в области задачи и названы, или зависимость поручения, чей принятый
+  результат входит в SHA, а собственный кандидат изменил файлы области записи
+  поручения. Без основания — `needs-lead` (остановка, решение ведущего): общий
+  зелёный тест на базе новой работы не доказывает. Без годного подтверждения,
+  при отклонении ревью или красном gate на базе — `empty-result`. С
+  основанием поручение принимается без нового коммита; основание пишется в
+  evidence ревью (`alreadySatisfied.basis`), и `engine.finish` повторяет
+  правило целиком по записанному, сверяя основание по зависимости с её
+  принятой попыткой.
 - **Область записи.** Изменения вне `writeScope`, защищённых путей и
   закреплённого контекста отклоняют попытку до интеграции.
 - **Gates.** Тестовый gate принимается по свежему непустому отчёту без
@@ -217,11 +260,32 @@ runtime-граф пакета.
   исполнение, завершено) сохраняется и переживает рестарт; владелец задания
   fenced. Упавшее поручение повторяется только по записанному классу отказа:
   в пределах повторов одинакового отпечатка для класса, попыток поручения
-  (`maxAttempts`) и бюджета восстановлений задания (`repairBudget`). Решение и
+  (`maxAttempts`) и бюджета восстановлений задания (`repairBudget`). Отказ
+  окружения или провайдера (и истёкшее владение) попытку поручения не
+  засчитывает, даже после кандидата: о работе он ничего не говорит; повторы
+  таких отказов ограничены паузой выдачи, пределом одинаковых отпечатков,
+  `repairBudget` и своим пределом на поручение (`MAX_NEUTRAL_FAILURES` = 3,
+  счётчик `neutralFailures`): на нём `retry` без сброса, выдача и
+  восстановление отказывают; сброс человека обнуляет счётчик. Попытка, прерванная штатной остановкой (`Runner.stop`),
+  не падает: черновик сохраняется, попытка помечается `interrupted:
+shutdown`, поручение возвращается в очередь (`ready`) без траты попытки и
+  без паузы по классу; после снятия паузы остановки она продолжается с
+  кандидата или черновика. Интегрированная попытка так не возвращается.
+  Решение и
   списание бюджета — одна транзакция с повтором. Отказ провайдера, отмена,
   неизвестный класс и устаревшая база — остановка с причиной. Восстановление
   снимает только свою причину паузы; паузу человека не снимает. Режим
-  `operator` автоматических повторов не делает.
+  `operator` автоматических повторов не делает. Тексты отказов ревью от
+  попытки к попытке разные, поэтому сверх отпечатка считается и названное:
+  два отказа ревью подряд по одному необъявленному свойству с тем же классом
+  входов (`classified`; класс сравнивается без регистра и лишних пробелов) —
+  пробел приёмки (`acceptanceGap`), остановка с `gap` и причиной для ведущего
+  вместо третьей слепой попытки. Совпадение только свойства или только класса
+  (`unboundProperties`, `inputClasses`) — слабее: общий класс бывает у разных
+  дефектов, поэтому нужно три отказа подряд.
+  Счёт — как у эпизода свойства: отказ окружения его не меняет, отказ gate,
+  другое название или новое основание поручения обрывают серию. Объявленные
+  свойства ведёт эпизод разбора.
 - **Переиспользование кандидата.** После отказа окружения или по времени,
   когда кандидат уже был, повтор берёт его вместо новой реализации, только
   если совпадают все основания: постановка, контракты, политика, runtime и
@@ -267,6 +331,12 @@ runtime-граф пакета.
   и файлы, не совпадающие с целевой веткой, отклоняются до вызова reviewer.
   Поручение включает механизм полем `properties`; свойства, которых нет в его
   договорах или которые исполняет не генеративный gate, не согласуются.
+  Обязательство может назвать несколько gates (`gates`) и способ
+  `reference`: сверку с закреплёнными эталонными наборами вместо генератора.
+  Gate эталонных наборов получает путь отчёта свойств и без `property` и
+  обязан подтвердить свою долю входов и семейств; пределы наборов (`gaps`)
+  reviewer контракта видит отдельно
+  ([договор](contracts.md#способы-исполнения-обязательства-property-и-reference)).
   Генеративный gate получает seed controller (`DEVCONTOUR_SEED`, свой у
   попытки, фазы и gate), селектор свойств и закреплённый корпус; отчёт
   свойств читается при любом исходе из каталога вне worktree. Gate проходит,
@@ -392,7 +462,11 @@ runtime-граф пакета.
   reviewer — получает последние 20 входов с ожиданием, наблюдением и командой.
   Это диагностика: gate не расширяет и корпусом не становится без
   подтверждения эталоном; обязательный корпус от ограничения реестра не
-  зависит.
+  зависит. Блокирующая находка со входом называет и нарушенное свойство или
+  критерий (`property`), и класс входов (`inputClass`) — генератор или
+  семейство, к которому относится пример. Класс записывается в реестр и на
+  отклонённую попытку (`inputClasses`); следующий writer получает задачу
+  чинить класс, а не экземпляр.
 - **Контекст плана и согласование.** Снимок контекста хранится по digest, а
   действующим становится только вместе с согласованием графа
   (`approval.context`). Пока новый снимок на ревью, после его отклонения,

package/docs/contracts.md

@@ -182,6 +182,106 @@ Git blob в репозитории `repositoryId`); `checks` — договор
 корпуса. Прошедший ревью документ хранится по digest (`contract-documents`):
 из него движок строит манифест генеративного gate поручения.
 
+#### Способы исполнения обязательства: `property` и `reference`
+
+Обязательство исполняют его gates: `obligations[].gates` (1–10 ID) или, без
+поля, `checks.gate`. Способ — `verification`:
+
+- `property` (поле не указано) — генеративная проверка, как прежде: каждый gate
+  обязательства генеративный (`gate.property`), отчёт свойств каждого
+  подтверждает полное покрытие обязательства (`coverage.minCases` и
+  семейства), корпус пополняет только gate договора;
+- `reference` — сверка с закреплёнными эталонными наборами. Ответы
+  независимого эталона (точный решатель, полный перебор, таблица DP)
+  получены заранее, сверены с другим способом и закреплены артефактами
+  контракта; gate сверяет с ними реализацию. Генератор не нужен, поэтому gate
+  может быть обычным test-gate без `property`.
+
+`reference` описывает:
+
+| Поле                                                            | Смысл                                                                                                                                                 |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oracle.description`, `oracle.limits`                           | эталон, его версия и пределы (время решения, что исключено из наборов)                                                                                |
+| `crossChecks[]` `{family, against, matches, total, artifacts?}` | сверка эталона с другим способом на семействе входов; `matches < total` — отказ; `artifacts` — закреплённый скрипт или журнал, воспроизводящий сверку |
+| `sets[]` `{gate, artifacts, minCases, families}`                | набор: gate, файлы набора (артефакты контракта), доля входов и семейств этого gate                                                                    |
+| `gaps`                                                          | чего наборы не доказывают: обобщение за пределы входов, классы вне наборов                                                                            |
+
+Структурные правила (`declarationProblems`, до вызова модели): у каждого gate
+обязательства есть набор, gate набора — среди gates обязательства, файлы
+наборов — артефакты контракта, сумма `sets[].minCases` не меньше
+`coverage.minCases`, сумма долей каждого семейства покрытия не меньше его
+`minCases`, семейства набора объявлены в покрытии и не превышают минимум
+набора, сверка эталона без расхождений, файлы сверки (`crossChecks[].artifacts`)
+— артефакты контракта; корпус у эталонного обязательства не включается.
+Требование генеративного gate к `reference` не применяется; остальные
+правила (`method`, бюджеты, spike) те же. Обязательство `property` любого
+обещания (и `invariant`, и `functional`) на gate без `property` отклоняется:
+поручение такое свойство выбрать не может (`orderPropertyProblems`), и
+договор был бы мёртвым.
+
+Доказательство — тот же отчёт свойств. Для gate, которому манифест поручения
+назначает эталонное свойство, controller задаёт путь отчёта
+(`DEVCONTOUR_PROPERTY_REPORT`) и селектор (`DEVCONTOUR_PROPERTIES`) и без
+`gate.property`. Запись манифеста эталонного свойства — доля этого gate:
+сумма `minCases` и семейств его наборов и `reference.artifacts` (файлы
+наборов); поле есть только у эталонных свойств, так что digest прежних
+манифестов не меняется. Gate проходит, только если отчёт называет свойство
+со статусом `passed`, числом проверенных входов и семейств не меньше доли и
+testcase с тем же ID в JUnit; зелёный JUnit и код 0 без отчёта — отказ
+(«Проверка по эталонным наборам не отчиталась»). Приёмка требует решающую
+запись обеих фаз с манифестом от каждого gate обязательства. Файлы наборов —
+артефакты контракта, поэтому попытка не может их изменить (защищённые пути).
+
+Reviewer контракта получает эталонные обязательства отдельно (`referenceNote`):
+эталон, сверку, наборы и `gaps`. Обещание, которое опирается только на
+`gaps`, без другого способа (генеративного свойства, инварианта,
+аналитического основания), — блокирующая находка. Сверка без `artifacts` —
+непроверенное утверждение автора, и reviewer оценивает её так.
+
+Ответы наборов лежат в рабочем дереве, поэтому реализация могла бы читать их
+или повторять их ответы и проходить каждый набор. Защита в два слоя:
+writer и reviewer кода получают список файлов наборов (`referenceSetFiles`,
+`referenceCodeNote`), и для reviewer чтение файлов наборов из кода
+реализации, вшитые ответы или особые случаи для входов наборов — блокирующая
+находка; controller отклоняет кандидата (`scope-violation`, до gates), если
+изменённый файл называет файл набора внутри строкового литерала (`'…'`,
+`"…"`, `` `…` ``): имя файла набора целым токеном — по краям нет буквы,
+цифры, `_`, `-` или `.`, так что путь и `../имя` совпадают, а `data.json` с
+набором `a.json` или `testcases.json` с `cases.json` — нет (`setFileReference`).
+Комментарии `//` и `/* */` и файлы без кода (`.md`, `.txt`, `.rst`, `.adoc`,
+каталог `docs/`) не проверяются. Тесты исполнителя, которые не артефакты
+контракта, проверяются тем же правилом: через них ответы тоже можно подать
+реализации. Остаточный риск: имя, собранное во время исполнения
+(`` `${name}-golden.json` ``), копия ответов без имени файла и обобщение,
+подогнанное под входы, механически не ловятся — их ловит ревью кода; строка
+кода, которая законно называет набор (не артефакт контракта), отклоняется.
+
+Пределы проверки долей: controller сверяет, что доли наборов покрывают
+общий минимум и минимумы семейств и что gate отчитался своей долей, но не
+сравнивает доли с размером файлов набора (сколько входов в нём на самом деле)
+и не проверяет, что входы различны. Reviewer контракта видит минимумы
+обязательства и семейств рядом с наборами (`referenceNote`) и оценивает это
+сам.
+
+#### ID testcase и отчёта
+
+Свойство, `testId` отчёта и testcase JUnit — один ID. ID testcase — это
+`classname.name` (без `classname` — `name`). Генератор отчёта задаёт
+`classname` по-своему: node:test (`--test-reporter=junit`) всегда пишет
+`classname="test"`, и тест `test('knapsack-optimal', …)` получает ID
+`test.knapsack-optimal` — таким должен быть и property ID; JUnit-отчёт
+собственного checker (как `harness.mjs` в примерах) пишет только `name`, и ID
+совпадает с именем. Если testcase с ID свойства нет, а есть
+`<classname>.<ID>`, отказ называет найденный ID.
+
+Совместимость: поля `gates`, `verification`, `reference` необязательны, договор
+без них разбирается, проверяется и даёт тот же манифест, digest и основание
+корпуса (`suiteBasis` включает новые поля, только когда они объявлены;
+`gates`, равные gate договора, — то же основание, что без поля, а digest
+документа контракта при этом другой).
+Версия договора остаётся `version: 1`; прежние версии harness договор с
+новыми полями отклоняют строгой схемой.
+
 ## Модель исполнения
 
 Схемы в `execution.ts` — то, что `ExecutionStore` хранит транзакционно:

package/docs/quickstart.md

@@ -13,7 +13,7 @@
 ```sh
 mkdir harness-demo && cd harness-demo
 npm init -y >/dev/null
-npm install --save-exact devcontour-harness@0.1.0-alpha.13
+npm install --save-exact devcontour-harness@0.1.0-alpha.18
 npx harness --version
 npx harness doctor
 ```

package/docs/release-notes/0.1.0-alpha.14.md

@@ -0,0 +1,69 @@
+# devcontour-harness 0.1.0-alpha.14
+
+> Локальный выпуск: в npm не публиковался. Его изменения вошли в
+> [0.1.0-alpha.15](0.1.0-alpha.15.md).
+
+Проверка по закреплённым эталонным наборам в договоре проверки и несколько
+gates у одного обязательства. Gates, `maxAttempts`, бюджеты попыток и
+повторов, правила находок, изоляция, принятие target ref и генеративная
+проверка (`property`) не менялись.
+
+## Что нового
+
+- **`verification: "reference"`.** Вычислительное обещание (оптимальность,
+  полнота, точность, производительность) можно проверить не генератором, а
+  наборами ответов независимого эталона, посчитанными заранее и закреплёнными
+  артефактами контракта. Обязательство описывает эталон и его пределы
+  (`oracle`), сверку эталона с другим способом (`crossChecks`: семейство,
+  способ, совпало из всего), наборы (`sets`: gate, файлы, доля входов и
+  семейств) и то, чего наборы не доказывают (`gaps`). Gate такого
+  обязательства — обычный test-gate без `property`
+  ([договор](../contracts.md#способы-исполнения-обязательства-property-и-reference)).
+- **`obligations[].gates`.** Обязательство называет свои gates (1–10); без
+  поля его исполняет `checks.gate`, как раньше. Генеративное обязательство
+  проверяет полное покрытие на каждом своём gate; эталонное — долю наборов
+  каждого gate.
+- **Доказательство доли.** Gate, которому манифест поручения назначает
+  эталонное свойство, получает путь отчёта свойств и селектор и без
+  `gate.property`. Отчёт обязан назвать свойство со статусом `passed` и
+  числом проверенных входов и семейств не меньше доли этого gate, JUnit —
+  testcase с тем же ID; зелёный JUnit и код 0 без отчёта — отказ gate.
+  Приёмка требует запись с манифестом от каждого gate обязательства.
+- **Структурные отказы до вызова модели:** gate обязательства без набора,
+  набор чужого gate, файл набора не среди артефактов контракта, доли наборов
+  меньше общего минимума или минимума семейства, семейство набора не из
+  покрытия, сверка эталона с расхождениями, корпус у эталонного
+  обязательства, корпус генеративного обязательства не на gate договора.
+- **Reviewer контракта** получает эталонные обязательства отдельно: эталон,
+  сверку, наборы и `gaps` (`referenceNote`). Обещание, которое опирается
+  только на `gaps`, — блокирующая находка.
+- Самопроверка исполнителя запускает и gates эталонных наборов.
+
+## Изменения договора
+
+Добавления в `checkDeclarationSchema`: `obligations[].gates`,
+`obligations[].verification` (`property` | `reference`) и
+`obligations[].reference`; в `CheckManifest.properties[]` — `reference`
+(только у эталонных свойств). Новые экспорты: `obligationGates`,
+`isReference`, `referenceNote`, `expectsReference`, `referenceSchema`. Без
+новых полей разбор, отказы, манифест, его digest и основание корпуса
+(`suiteBasis`) те же, что в alpha.13. Сообщение «… не генеративный (нет
+property)» теперь называется для каждого gate генеративного обязательства.
+
+## Совместимость
+
+Формат состояния тот же. Договор с новыми полями alpha.13 и раньше не
+принимают (строгая схема): состояние с таким контрактом откатывается только
+через копию. Обновление и откат — по [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` (lint, typecheck, schemas, build, весь набор тестов, package
+smoke из установленного архива) на macOS arm64, Node.js 24.3.
+`tests/reference.test.ts`: структурные отказы и принятый договор на gates без
+генератора, манифест доли gate, прежние манифест и основание корпуса
+договора без новых полей, согласование поручения, подсказка reviewer,
+самопроверка; на fixture runtime — два gate эталонных наборов доводят
+поручение до приёмки, недобор входов при зелёном JUnit и коде 0, отсутствие
+отчёта и расхождение с эталоном — отказ gate. Каждая новая проверка падает на
+своём мутанте реализации. Живые модели не вызывались.

package/docs/release-notes/0.1.0-alpha.15.md

@@ -0,0 +1,62 @@
+# devcontour-harness 0.1.0-alpha.15
+
+> Локальный выпуск: в npm не публиковался. Его изменения вошли в
+> [0.1.0-alpha.16](0.1.0-alpha.16.md).
+
+Защита эталонной проверки от подгонки под наборы, закреплённые файлы сверки
+эталона и ID testcase node:test. Включает всё из
+[0.1.0-alpha.14](0.1.0-alpha.14.md): alpha.14 — локальный выпуск, в npm не
+публиковался; первая публикуемая версия с эталонными наборами — alpha.15.
+Gates, `maxAttempts`, бюджеты попыток и повторов, правила находок, изоляция,
+принятие target ref и формат состояния не менялись.
+
+## Что нового
+
+- **Ответы наборов не подсказка реализации.** Writer и reviewer кода получают
+  список файлов эталонных наборов поручения. Для reviewer чтение их из кода
+  реализации, вшитые ответы и особые случаи для входов наборов — блокирующая
+  находка. Controller отклоняет кандидата до gates (`scope-violation`
+  «Реализация ссылается на файлы эталонных наборов»), если изменённый файл
+  содержит путь или имя файла набора. Имя, собранное во время исполнения, и
+  копия ответов без имени файла механически не ловятся — их ловит ревью кода
+  ([договор](../contracts.md#способы-исполнения-обязательства-property-и-reference)).
+- **`crossChecks[].artifacts`.** Сверка эталона может ссылаться на
+  закреплённый скрипт или журнал, который её воспроизводит; файлы обязаны
+  быть артефактами контракта. Reviewer контракта оценивает сверку без них
+  как непроверенное утверждение автора.
+- **Мёртвые обязательства.** Обязательство `property` любого обещания на
+  gate без `property` отклоняется до вызова модели: поручение его выбрать не
+  может. Прежде так отклонялись только вычислительные обещания.
+- **ID testcase.** Отказ «testcase X отсутствует в JUnit» называет найденный
+  `<classname>.X` (node:test пишет `classname="test"`, и ID свойства для него
+  — `test.<имя теста>`); правило описано в
+  [договоре](../contracts.md#id-testcase-и-отчёта).
+- Сообщение отказа gate, где генеративные и эталонные свойства вместе:
+  «Проверка свойств и эталонных наборов …».
+- `gates` обязательства, равные `checks.gate`, дают то же основание корпуса,
+  что и без поля.
+
+## Изменения договора
+
+Добавления: `reference.crossChecks[].artifacts` (1–10 путей), экспорты
+`referenceSetFiles` и `referenceCodeNote`. Изменение отказа: обязательство
+`property` с необязательным обещанием (`functional`, `invariant`, `other`) на
+gate без `property` теперь — структурный отказ договора (текст «… не
+генеративный (нет property) — поручение не сможет выбрать это свойство; …»;
+у вычислительных обещаний текст тоже дополнен). Договор без новых полей даёт
+тот же манифест, digest и основание корпуса.
+
+## Совместимость
+
+Формат состояния тот же. Договор с новыми полями alpha.13 и раньше не
+принимают (строгая схема). Обновление и откат — по [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` на macOS arm64, Node.js 24.3. `tests/reference.test.ts`
+(14 тестов): к проверкам alpha.14 добавлены отказ кандидата, читающего файл
+набора, список наборов в запросах writer и reviewer, testcase с другим ID,
+настоящий JUnit node:test (`test.<имя>`), файлы сверки, мёртвое
+обязательство-инвариант, основание корпуса при `gates` равных gate договора.
+Каждая новая проверка падает на своём мутанте (29 из 29). Живые модели не
+вызывались.

package/docs/release-notes/0.1.0-alpha.16.md

@@ -0,0 +1,36 @@
+# devcontour-harness 0.1.0-alpha.16
+
+Проверка файлов эталонных наборов без ложных отказов. Включает всё из
+[0.1.0-alpha.15](0.1.0-alpha.15.md) и [0.1.0-alpha.14](0.1.0-alpha.14.md):
+обе — локальные выпуски, в npm не публиковались; первая публикуемая версия с
+эталонными наборами — alpha.16. Gates, `maxAttempts`, бюджеты попыток и
+повторов, правила находок, изоляция, принятие target ref и формат состояния
+не менялись.
+
+## Что нового
+
+- **Отказ по файлу набора — только по строковому литералу.** В alpha.15
+  кандидат отклонялся, если изменённый файл где угодно содержал путь или имя
+  файла набора: комментарий, свой тест исполнителя, `data.json` при наборе
+  `a.json`. Теперь имя файла набора должно стоять целым токеном внутри
+  строкового литерала (`'…'`, `"…"`, `` `…` ``); комментарии `//` и `/* */` и
+  файлы без кода (`.md`, `.txt`, `.rst`, `.adoc`, `docs/`) не проверяются.
+  Тесты исполнителя проверяются тем же правилом. Ложный отказ тратил попытку.
+- **Reviewer контракта видит минимумы.** `referenceNote` показывает общий
+  минимум обязательства, минимумы семейств и доли семейств каждого набора.
+  Сравнения долей с фактическим размером файлов набора нет — это описано в
+  [договоре](../contracts.md#способы-исполнения-обязательства-property-и-reference).
+- Новый экспорт `setFileReference(path, text, sets)`.
+
+## Совместимость
+
+Формат состояния и договор те же, что в alpha.15. Обновление и откат — по
+[upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` на macOS arm64, Node.js 24.3. `tests/reference.test.ts`
+(15 тестов): комментарий, текст, свой тест без литерала, похожие имена и
+непарная кавычка — без отказа; литеральный путь, `'golden-a.json'`, путь в
+шаблоне, `../имя` и импорт из теста исполнителя — отказ. 36 из 36 мутантов
+реализации обнаружены. Живые модели не вызывались.

package/docs/release-notes/0.1.0-alpha.17.md

@@ -0,0 +1,86 @@
+# devcontour-harness 0.1.0-alpha.17
+
+Меньше слепых повторов и ручных сбросов. Включает всё из
+[0.1.0-alpha.16](0.1.0-alpha.16.md). Gates, правила находок, изоляция,
+принятие target ref и `maxAttempts` не менялись; формат состояния получил
+необязательные поля (ниже, «Совместимость»).
+
+## Что нового
+
+- **Класс входов в находке ревью.** Блокирующая находка со входом называет
+  нарушенное свойство или критерий (`reproduction.property`) и класс входов
+  (`reproduction.inputClass`) — генератор или семейство, а не экземпляр. Поле
+  обязательно в схеме ответа runtime; ответ прежней формы без него
+  разбирается. Класс пишется в реестр воспроизведений и на отклонённую
+  попытку (`inputClasses`, пары `classified`); следующий writer получает
+  задачу чинить класс.
+- **Пробел приёмки.** `repairDecision` останавливает поручение с полем `gap`
+  и причиной для ведущего, когда два отказа ревью подряд называют одно и то
+  же необъявленное свойство с тем же классом входов (класс без регистра и
+  лишних пробелов). Совпадение только свойства или только класса требует
+  трёх отказов подряд: общий класс бывает у разных дефектов. Отказ
+  окружения серию не меняет; отказ gate, другое название и новое основание
+  поручения её обрывают. `explain` показывает то же. Объявленные свойства
+  по-прежнему ведёт эпизод разбора.
+- **Отказы окружения не тратят попытки.** Отказ окружения или провайдера и
+  истёкшее владение не засчитываются в `maxAttempts`, и после кандидата.
+  Предел у них свой: `MAX_NEUTRAL_FAILURES` = 3 на поручение (счётчик
+  `neutralFailures`); на нём `retry` без сброса, выдача и восстановление
+  отказывают, сброс человека обнуляет счётчик.
+- **Штатная остановка не роняет работу.** `Runner.stop` помечает свои
+  попытки: прерванная сохраняет черновик, получает `interrupted: shutdown`,
+  а поручение возвращается в очередь (`ready`) без траты попытки и без паузы
+  по классу отказа; после снятия паузы остановки следующая попытка
+  продолжает с кандидата или черновика. Интегрированная попытка так не
+  возвращается: это обычный отказ, хост получает `hooks.failed`.
+- **Класс отказа `unfinished`.** `completed: false` исполнителя был
+  `unknown` и останавливал работу без повтора, с сохранённым черновиком.
+  Теперь это `unfinished`: повтор (предел одинаковых — 2) продолжает с
+  черновика (`continuedFrom.kind: unfinished`) в пределах `maxAttempts` и
+  `repairBudget`; для эпизода свойства отказ нейтрален.
+- **Пустой результат только с механическим основанием.** Пустая реализация
+  больше не отклоняется сразу: кандидат — сама база, gates задачи идут на
+  ней, оба ревью отвечают схемой с обязательным `alreadySatisfied` (gates
+  области задачи — хотя бы один test gate и все gates договоров проверки
+  поручения — и основание). Принятие требует ещё механического основания,
+  которое находит controller: договор проверки поручения со всеми gates в
+  области задачи, или зависимость, чей принятый результат входит в
+  проверяемый SHA и чей кандидат менял файлы области записи поручения.
+  Основание пишется в evidence ревью (`alreadySatisfied.basis`). Без него —
+  новый класс отказа `needs-lead`: остановка без повтора, решение ведущего.
+  `engine.finish` повторяет правило целиком по записанным данным.
+- **`runGatesAt`.** Именованные gates компонента (с предпосылками) на
+  закреплённом SHA вне попытки — тем же путём, что интеграция задачи: свой
+  worktree, снимки зависимостей, ресурсы, lifecycle и prepare, окружение
+  интеграции, песочница проверок; каждый evidence — через callback хоста,
+  первый провал останавливает прогон, дерево должно остаться прежним.
+- **Учёт стоимости по всему потоку.** Адаптер CLI разбирает stdout по
+  строкам по мере поступления и хранит только поля телеметрии (последний
+  `result` claude, `turn.completed` codex, первая названная модель): цена
+  длинного вызова больше не теряется за пределом хвоста вывода. Разбор
+  ограничен по памяти и не бросает исключений из обработчика вывода.
+- **Отчёт свойств в пробах ревьюера.** Проба gate получает путь отчёта
+  свойств в scratch controller (`HARNESS_PROPERTY_REPORT`,
+  `DEVCONTOUR_PROPERTY_REPORT` — та же переменная, что у движка) и сохраняет
+  копию отчёта как evidence пробы; отчёт-ссылка отклоняется.
+
+## Совместимость
+
+Новые необязательные поля попытки (`interrupted`, `inputClasses`,
+`classified`), поручения (`neutralFailures`), записи воспроизведения
+(`inputClass`), evidence ревью (`alreadySatisfied`) и классы отказа
+`unfinished` и `needs-lead`; в схемах данных CLI это единственные
+аддитивные изменения перечней. Прежние записи не меняются.
+Строгие схемы прежних версий новых значений не знают: после первой записи
+alpha.17 откат — только через копию. Изменение поведения: тесты хоста,
+ждавшие засчитанную попытку после отказа окружения или `failed` после
+штатной остановки, нужно обновить. Матрица — [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` на macOS arm64, Node.js 24.3. Новые тесты на fixture runtime
+и реальных Git-фикстурах (`repair`, `reproductions`, `runner` T14,
+`explain-engine`, `network-recovery`, `reuse`, `usage`, `probe-gates`,
+`already-satisfied`, `gates-at`); каждый новый тест обнаруживает свой мутант
+реализации. Закрепление схем данных CLI (H3-01) сверяет байты H2 без
+аддитивных значений `unfinished` и `needs-lead`. Живые модели не вызывались.

package/docs/release-notes/0.1.0-alpha.18.md

@@ -0,0 +1,48 @@
+# devcontour-harness 0.1.0-alpha.18
+
+Проверка gates на закреплённом SHA исполняет их с теми предпосылками, на
+которые опирается профиль. Включает всё из [0.1.0-alpha.17](0.1.0-alpha.17.md).
+Формат состояния, gates попыток, правила находок, изоляция, принятие target
+ref и `maxAttempts` не менялись.
+
+## Что нового
+
+- **Предпосылки проверки вне задачи.** `runGatesAt` брал только явные
+  `dependsOn`. В профиле, который опирается на порядок массива (установка
+  первой, без `dependsOn`), проверка одного test gate шла без установки и
+  падала на отсутствующих модулях, хотя задачи проходили: их область называла
+  установку явно. Теперь область проверки — названные gates и предпосылки
+  каждого (`standaloneScope`), порядок — тот же `orderedScope`, что у попытки
+  (прежний внутренний `ordered` runner, без изменения поведения).
+  Предпосылки (`gatePrerequisites`): у gate с объявленным `dependsOn` —
+  замыкание по `dependsOn`; у gate без поля `dependsOn` — все более ранние
+  gates вида `check` со своими предпосылками. Более ранние test gates не
+  добавляются. Каждый gate посещается один раз, поэтому `dependsOn` на более
+  поздний gate вместе с неявным ребром не зацикливается. Область задачи
+  по-прежнему исполняется как записана.
+- **Явный `dependsOn: []` — без предпосылок.** Объявленный пустой
+  `dependsOn` — режим графа: неявных предпосылок нет. Порядок массива
+  действует только для gate без поля.
+- **Все провалы сразу.** Провал gate больше не останавливает проверку:
+  исполняются все названные gates, результат перечисляет каждый непрошедший
+  (`failures`; `failure` — первый, как раньше). Пропускается только gate,
+  чья явная предпосылка (`dependsOn`, `explicitPrerequisites`) не прошла, — он
+  назван с этой причиной. Провал неявной предпосылки (раннего check gate) не
+  скрывает исход тестов: исполняются и названы оба. Evidence по-прежнему
+  пишется через запись хоста и привязано к SHA.
+
+## Совместимость
+
+Формат состояния не меняется. `GatesAtResult` получает поле `failures`;
+хост, ждавший остановки на первом провале, получает теперь все исполненные
+gates. Новые экспорты: `orderedScope`, `gatePrerequisites`,
+`explicitPrerequisites`, `standaloneScope`. Матрица — [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+Затронутые тесты на реальных Git-фикстурах (`gates-at`: профиль в порядке
+массива с установкой первой и без `dependsOn`, петля через неявное ребро,
+пустой `dependsOn`, цепочки двух и трёх уровней, смешанная цепочка, провал
+неявной предпосылки; `runner` T01, T09); каждый новый тест обнаруживает свой
+мутант реализации. Полный `npm run check` перед публикацией выполняет
+ведущий. Живые модели не вызывались.