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

package/docs/quickstart.md

@@ -0,0 +1,182 @@
+# Quickstart
+
+Пять минут от пустого каталога до принятого поручения. Пример — вымышленный
+репозиторий `greeting` с одной задачей: добавить функцию `greet(name)`.
+
+## 1. Что понадобится
+
+- Node.js ≥ 24.3.0 и Git.
+- Установленные и авторизованные CLI `claude` и `codex` — writer и reviewer
+  примера. `harness doctor` проверяет их без вызова модели.
+- npm (идёт с Node.js) — для установки из registry или из локального архива.
+
+```sh
+mkdir harness-demo && cd harness-demo
+npm init -y >/dev/null
+npm install --save-exact devcontour-harness@0.1.0-alpha.5
+npx harness --version
+npx harness doctor
+```
+
+Вместо точной версии можно взять текущую alpha: `devcontour-harness@alpha`.
+Без registry пакет ставится из архива:
+`npm install --omit=dev --ignore-scripts ./devcontour-harness-<version>.tgz`.
+
+CLI установлен локально, в `node_modules/.bin` каталога `harness-demo`.
+`npx harness` находит его из этого каталога и его подкаталогов (дальше
+работа идёт в `harness-demo/greeting`); глобальная команда `harness` не
+нужна.
+
+## 2. Репозиторий и входы
+
+```sh
+cp -R node_modules/devcontour-harness/examples/single-task greeting
+cd greeting
+git init -q -b main && git add -A && git commit -qm init
+```
+
+В каталоге:
+
+| Файл                      | Что это                                                          |
+| ------------------------- | ---------------------------------------------------------------- |
+| `graph.json`              | `WorkGraph`: одно поручение `add-greeting` с критериями приёмки  |
+| `policy.json`             | `ExecutionPolicy`: репозиторий, gate `unit` с JUnit, роли, ревью |
+| `policy-same-vendor.json` | Та же политика, но reviewer того же вендора, разрешённый явно    |
+| `test/run.js`             | Проверка: пишет JUnit-отчёт в путь из `DEVCONTOUR_REPORT_PATH`   |
+
+Поручение в `graph.json`:
+
+```json
+{
+  "id": "add-greeting",
+  "title": "Add a greeting function",
+  "goal": "Add greet(name) to src/greet.js returning 'Hello, <name>!'.",
+  "acceptance": ["greet('Ada') returns 'Hello, Ada!'", "npm test passes with a JUnit report"],
+  "role": "developer",
+  "repositoryId": "app",
+  "writeScope": ["src"],
+  "gates": ["unit"]
+}
+```
+
+## 3. Проверить входы
+
+```sh
+npx harness validate --graph graph.json --policy policy.json
+```
+
+Команда не вызывает моделей и ничего не пишет. В ответе — digests графа и
+политики и число поручений. Любая ошибка — exit 2 и список `issues` с путями.
+
+## 4. Запустить
+
+```sh
+npx harness run --graph graph.json --policy policy.json \
+  --state ../greeting-state --author external --sink file:../greeting-results
+```
+
+`run`:
+
+1. регистрирует граф и проводит техническое ревью плана reviewer-ом из
+   политики (здесь — codex);
+2. согласует граф (`approvalMode: agent`; при `operator` нужен `harness approve`);
+3. выдаёт попытку writer-у (claude) в отдельном Git worktree;
+4. прогоняет gate `unit` и независимое ревью на candidate SHA;
+5. интегрирует кандидата с текущей принятой веткой, снова прогоняет gate и
+   ревью — уже на integration SHA;
+6. продвигает `refs/heads/harness/accepted` compare-and-swap и записывает
+   результат; `--sink` доставляет его в каталог `../greeting-results`.
+
+Основная ветка и рабочее дерево не меняются. Повторный `run` той же редакции
+графа продолжает работу и не создаёт второй попытки.
+
+## 5. Прочитать результат
+
+```sh
+npx harness result --state ../greeting-state --work add-greeting
+```
+
+Сокращённый ответ (SHA и digests здесь условные):
+
+```json
+{
+  "apiVersion": "devcontour-harness/v1alpha1",
+  "command": "result",
+  "ok": true,
+  "data": {
+    "apiVersion": "devcontour-harness/v1alpha1",
+    "result": {
+      "outcome": "accepted",
+      "workOrderId": "add-greeting",
+      "graphId": "greeting",
+      "runId": "…",
+      "attempt": 1,
+      "repositoryId": "app",
+      "targetRef": "refs/heads/harness/accepted",
+      "shas": {
+        "base": "1111…",
+        "candidate": "2222…",
+        "integration": "3333…",
+        "result": "3333…"
+      },
+      "inputs": {
+        "harnessVersion": "<version>",
+        "stateVersion": 1,
+        "workOrderDigest": "…",
+        "graphDigest": "…",
+        "policyDigest": "…",
+        "writer": "claude"
+      },
+      "evidence": [
+        { "kind": "test", "phase": "candidate", "gate": "unit", "sha": "2222…", "passed": true },
+        {
+          "kind": "review",
+          "phase": "candidate",
+          "gate": "independent-review",
+          "sha": "2222…",
+          "passed": true
+        },
+        { "kind": "test", "phase": "integration", "gate": "unit", "sha": "3333…", "passed": true },
+        {
+          "kind": "review",
+          "phase": "integration",
+          "gate": "independent-review",
+          "sha": "3333…",
+          "passed": true
+        }
+      ],
+      "findings": [],
+      "limitations": [],
+      "finishedAt": "…"
+    },
+    "delivery": [{ "sink": "files", "status": "delivered", "attempts": 1 }]
+  }
+}
+```
+
+## 6. Проверить result SHA
+
+```sh
+git rev-parse refs/heads/harness/accepted      # = data.result.shas.result
+git merge-base --is-ancestor <shas.base> refs/heads/harness/accepted && echo ok
+git show --stat refs/heads/harness/accepted    # изменения только в src/
+```
+
+`result` должен совпасть с вершиной target ref; каждый PASS в `evidence`
+относится ровно к `candidate` или `integration` SHA своей фазы.
+
+## 7. Что дальше
+
+- Пауза и продолжение: `harness pause --state D`, `harness resume --state D`.
+- Отмена и повтор: `harness cancel --work ID`, `harness retry --work ID`.
+- События: `harness events --state D --after N`.
+- Один вендор: запустите с `--policy policy-same-vendor.json` — reviewer того
+  же вендора допускается только потому, что политика это явно разрешает.
+- Другие конфигурации — в `examples/` этого руководства.
+
+Исход без принятия (`rejected`, `blocked`, `stopped`, `cancelled`) несёт
+`stopReason{code, message}`; result SHA у него нет. Exit codes: 0 успех,
+2 неверный вход, 3 отказ или блокировка, 4 инфраструктура.
+
+Тесты пакета используют fixture executables вместо живых CLI; их
+результаты проверяют механику, а не качество моделей.

package/docs/upgrade.md

@@ -0,0 +1,166 @@
+# Обновление и откат
+
+Документ описывает, какие форматы поддерживает пакет, как обновить установку
+и как откатиться. Процедуры одинаковы для standalone-состояния harness и для
+хоста, который держит состояние в своём хранилище (например, DevContour с
+центральной базой или базами компонентов).
+
+## Версии
+
+| Что             | Правило                                                                     |
+| --------------- | --------------------------------------------------------------------------- |
+| Пакет           | `0.1.0-alpha.N`; выпущенная версия неизменяема (тот же номер — те же байты) |
+| Публичный API   | `devcontour-harness/v1alpha1`                                               |
+| Политика        | `policyVersion: 1`                                                          |
+| Состояние       | `stateVersion: 1`                                                           |
+| Отчёты и корпус | `version: 1` (отчёт свойств, договор проверки, корпус, receipt среды)       |
+
+Для `0.x`: patch — совместимые исправления; minor — отдельно описанные
+изменения договора, включая несовместимые. Неизвестная версия входа, политики
+или состояния отклоняется до любой записи и до выдачи попытки.
+
+## Матрица форматов
+
+| Состояние, записанное…                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Пишет поверх | Примечание                                                                          |
+| ---------------------------------------------- | ------------------------ | ------------------------ | ------------ | ----------------------------------------------------------------------------------- |
+| 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`. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
+формата до записи проверяют тесты совместимости пакета
+(`tests/compatibility.test.ts`).
+
+Новые версии добавляют только необязательные поля и новые пространства
+локальных записей. Схемы состояния строгие: прежняя версия отклоняет
+незнакомое поле до любой записи, а не сохраняет его молча. Поэтому откат
+пакета «формат совместим» возможен только для состояния без новых полей,
+иначе — восстановление копии (таблица «Откат» ниже).
+
+### alpha.2: версия движка в роли controller
+
+Роль controller записывает версию движка (`engineVersion`). Процесс другой
+версии — и процесс прежней версии, записавший роль без версии, — живую роль
+не перенимает, даже под тем же именем владельца: `harness run` получает
+`CONTROLLER_BUSY` с обеими версиями, выдачи нет. После истечения срока роль
+переходит штатно, а активные попытки прежней версии проходят recovery без
+повторного использования кандидата. Штатная остановка снимает роль целиком.
+
+### alpha.3: версии движка в `doctor`
+
+Формат состояния тот же, что у alpha.2 (столбец alpha.2 матрицы относится и
+к alpha.3). `harness doctor --state D` читает состояние строгой схемой этой
+версии и для совместимого состояния называет версии движка, записавшие его
+(`state.engineVersions`: роль controller и попытки); состояние, которое эта
+версия не читает, отмечается несовместимым без записи.
+
+### alpha.4: открытие без записи и владение попыткой по версии
+
+- Существующее состояние сначала проверяется целиком соединением только для
+  чтения: версия формата и документ строгой схемой. Несовместимое состояние
+  отклоняется до создания таблиц, записи автора (`meta.writer`) и смены
+  journal mode — файл остаётся байт в байт прежним. `harness doctor --state`
+  открывает состояние только для чтения и автором не становится.
+- Операции активной попытки (продление, фаза, evidence, принятие, отказ) и
+  совместной проверки выполняет только движок той версии, что их начал.
+  Другая версия — и попытка без версии, записанная до её появления, — получает
+  `LEASE_STALE` даже с верным token до истечения срока; продолжение — только
+  через истечение и recovery с новым владением.
+- Совместная проверка записывает `engineVersion`; состояние, где она есть,
+  прежние версии не читают (строка матрицы выше), поэтому откат с alpha.4 на
+  более раннюю версию после первой совместной проверки — только через копию.
+
+### alpha.5: публикация в npm
+
+Код движка, форматы состояния, политики, отчётов и публичный API те же, что
+у alpha.4; меняются поставка (npm, тег `alpha`) и номер версии. Состояние
+alpha.4 alpha.5 читает и пишет без преобразования, состояние alpha.5 читает
+alpha.4 (новых полей нет).
+
+Номер версии — это `engineVersion`, поэтому правила alpha.2–alpha.4
+действуют и между alpha.4 и alpha.5:
+
+- живая роль controller alpha.4 не переходит к alpha.5 (`CONTROLLER_BUSY`),
+  пока не будет снята штатной остановкой или не истечёт;
+- активную попытку и совместную проверку, начатые alpha.4, alpha.5 не
+  продолжает даже с верным token (`LEASE_STALE`): после истечения срока
+  recovery передаёт их новой версии без повторного использования кандидата
+  прежней версии;
+- в обратную сторону то же: после отката alpha.4 не продолжает попытки
+  alpha.5.
+
+Поэтому обновление — по общей процедуре ниже: остановить writers, сделать
+копию, проверить её новой версией. У хоста, который поставлял alpha.4
+архивом, переход на registry — смена зависимости на точную версию
+`0.1.0-alpha.5` и обновление lock; содержимое alpha.4 под своим номером не
+меняется.
+
+## Перед обновлением
+
+1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
+   дождаться завершения или явно остановить активные попытки, остановить
+   controller, сервер и всех остальных, кто пишет в состояние. Одной паузы
+   очереди недостаточно.
+2. **Зафиксировать.** Версии пакета и потребителя, конфигурацию, вершины
+   target refs и result SHA принятых поручений (`git rev-parse` каждого
+   target ref, `harness result` каждого поручения).
+3. **Сделать копию.**
+   - standalone — каталог `--state` целиком, пока controller остановлен;
+   - центральная база хоста — штатная согласованная копия SQLite;
+   - базы компонентов — копия **всех** баз при остановленных writers
+     (команда резервной копии одной базы этого не обеспечивает).
+     Git-объекты должны оставаться доступными: копия базы без объектов, на
+     которые она ссылается, не восстанавливает историю.
+4. **Проверить на копии.** Открыть копию новой версией в отдельном каталоге
+   (`harness doctor --state <копия>`, `harness status --state <копия>`).
+   Проверка несовместимой версии не должна менять данные — сравните хэши
+   файлов копии до и после.
+
+## Обновление
+
+1. Установить новую версию точно (у хоста — смена зависимости и lock):
+   - из npm — `npm install --save-exact devcontour-harness@<new>`;
+   - из архива — `npm install --omit=dev --ignore-scripts ./devcontour-harness-<new>.tgz`.
+2. `harness doctor --state D` — версии, runtime, песочница, совместимость и
+   версии движка, записавшие состояние (`state.engineVersions`: роль
+   controller и попытки).
+3. Возобновить работу **одним** controller (`harness resume`, `harness run`).
+4. Попытки, активные во время остановки, не продолжаются со старыми
+   токенами: recovery либо принимает сохранённый integration SHA при полных
+   актуальных evidence, либо завершает попытку; новая попытка получает новое
+   владение и новые проверки. Кандидат попытки прежней версии движка повторно
+   не используется.
+
+Установка новой версии не меняет политику, профили, закрепления контекста,
+инструкции агентам и принятые результаты.
+
+## Откат
+
+| Ситуация                              | Действие                                                                                                                                                        |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Изменения исходников до выкатки       | Вернуться к проверенной паре коммитов/версий в отдельном checkout или revert-коммитами; страховочную ветку не переписывать                                      |
+| Только пакет, формат данных совместим | Остановить writers → вернуть прежнюю версию (архив или точную версию npm), зависимость и lock → `harness doctor` → возобновить                                  |
+| Новая версия уже изменила формат      | Остановить writers → восстановить согласованную копию вместе с совместимой версией пакета → сверить Git refs и артефакты (ниже); простого понижения версии мало |
+
+### Сверка Git после восстановления базы
+
+База и Git не образуют одну транзакцию. Если после копии target ref ушёл
+вперёд (поручение принято уже новой версией), восстановленная база не знает
+об этом принятии.
+
+1. Для каждого репозитория сравните вершину target ref с зафиксированной до
+   обновления и с result SHA, известными восстановленной базе.
+2. Коммиты, которых база не знает, — принятые после копии. Их нельзя молча
+   «забыть»: либо повторите поручения новой попыткой (её интеграция
+   продолжит текущий target ref), либо явно задокументируйте, что эти
+   принятия выполнены вне восстановленного состояния.
+3. Не выполняйте `git reset --hard` пользовательского репозитория и не
+   переписывайте target ref ради совпадения с базой — это не откат, а потеря
+   принятой работы.
+
+Откат объявляется успешным, только когда для каждого target ref известно,
+какие его коммиты учтены восстановленным состоянием.

package/examples/README.md

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

package/examples/external-connector/README.md

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

package/examples/external-connector/connector.mjs

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

package/examples/files-only/README.md

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

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

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

package/examples/files-only/graph.json

@@ -0,0 +1,23 @@
+{
+  "apiVersion": "devcontour-harness/v1alpha1",
+  "id": "notes",
+  "source": { "connector": "files", "ref": "graph.json", "revision": "1" },
+  "orders": [
+    {
+      "apiVersion": "devcontour-harness/v1alpha1",
+      "id": "add-tags",
+      "source": { "connector": "files", "ref": "add-tags", "revision": "1" },
+      "title": "Add tags to notes",
+      "goal": "Notes accept a list of tags; tags are trimmed and deduplicated.",
+      "acceptance": [
+        "createNote({ tags: [' a', 'a', 'b'] }) stores ['a', 'b']",
+        "npm test passes with a JUnit report"
+      ],
+      "role": "developer",
+      "repositoryId": "app",
+      "writeScope": ["src", "test"],
+      "gates": ["unit"],
+      "context": ["norms"]
+    }
+  ]
+}

package/examples/files-only/policy.json

@@ -0,0 +1,30 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["npm", "test"],
+          "timeoutMs": 240000,
+          "report": { "type": "junit", "path": ".reports/junit.xml" }
+        }
+      ],
+      "protectedPaths": [".github/", "package-lock.json", "policy.json", "graph.json"]
+    }
+  ],
+  "roles": {
+    "developer": { "writer": { "runtime": "claude" }, "writePaths": ["src", "test"] }
+  },
+  "review": {
+    "code": { "reviewer": { "runtime": "codex" } },
+    "plan": { "reviewer": { "runtime": "codex" }, "alternates": [{ "runtime": "claude" }] },
+    "contract": { "reviewer": { "runtime": "codex" }, "alternates": [{ "runtime": "claude" }] }
+  },
+  "maxAttempts": 3,
+  "budgets": { "work": { "usd": 5 }, "total": { "usd": 50 }, "onUnknown": "stop" }
+}

package/examples/one-vendor/README.md

@@ -0,0 +1,19 @@
+# Один вендор
+
+Writer и reviewer — claude. Это разрешено только потому, что каждое правило
+ревью явно говорит `"vendor": "same-vendor-allowed"`. Без этой строки
+`harness validate` отклоняет политику (`REVIEWER_SAME_VENDOR`).
+
+Что сохраняется и при одном вендоре:
+
+- reviewer — отдельная роль и отдельный вызов со свежей сессией: в его запросе
+  нет разговора, отчёта и идентификатора сессии writer;
+- reviewer получает исходные критерии приёмки, закреплённый контекст, diff,
+  evidence проверенного SHA и прежние находки;
+- reviewer работает только на чтение: правка дерева или HEAD делает его
+  ответ недействительным;
+- приёмка требует тех же gates и ревью обеих фаз; разные модели не нужны.
+
+Тот же эффект для одного runtime без смены вендора по умолчанию даёт
+`alternates`: reviewer `codex`, запасной `claude` — для автора codex будет
+выбран claude только при `same-vendor-allowed`.

package/examples/one-vendor/policy.json

@@ -0,0 +1,27 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["npm", "test"],
+          "report": { "type": "junit", "path": ".reports/junit.xml" }
+        }
+      ],
+      "protectedPaths": [".github/", "package-lock.json", "policy.json", "graph.json"]
+    }
+  ],
+  "roles": {
+    "developer": { "writer": { "runtime": "claude" } }
+  },
+  "review": {
+    "code": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" },
+    "plan": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" },
+    "contract": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" }
+  }
+}

package/examples/single-task/README.md

@@ -0,0 +1,18 @@
+# Пример: одна задача
+
+Вымышленный репозиторий с одним поручением: добавить `greet(name)` в
+`src/greet.js`. Проверка — `node test/run.js`, она пишет JUnit-отчёт в путь из
+`DEVCONTOUR_REPORT_PATH`.
+
+```sh
+cp -R node_modules/devcontour-harness/examples/single-task greeting && cd greeting
+git init -q && git add -A && git commit -qm init
+npx harness validate --graph graph.json --policy policy.json
+npx harness run --graph graph.json --policy policy.json --state ../greeting-state --author external --sink file:../greeting-results
+npx harness result --state ../greeting-state --work add-greeting
+git rev-parse refs/heads/harness/accepted   # совпадает с result.shas.result
+```
+
+`policy.json` — writer claude, reviewer codex (разные вендоры).
+`policy-same-vendor.json` — reviewer того же вендора, разрешённый явно.
+Для запуска нужны установленные и авторизованные CLI `codex` и `claude`.

package/examples/single-task/graph.json

@@ -0,0 +1,27 @@
+{
+  "apiVersion": "devcontour-harness/v1alpha1",
+  "id": "greeting",
+  "source": {
+    "connector": "files",
+    "ref": "graph.json",
+    "revision": "1"
+  },
+  "orders": [
+    {
+      "apiVersion": "devcontour-harness/v1alpha1",
+      "id": "add-greeting",
+      "source": {
+        "connector": "files",
+        "ref": "add-greeting",
+        "revision": "1"
+      },
+      "title": "Add a greeting function",
+      "goal": "Add greet(name) to src/greet.js returning 'Hello, <name>!'.",
+      "acceptance": ["greet('Ada') returns 'Hello, Ada!'", "npm test passes with a JUnit report"],
+      "role": "developer",
+      "repositoryId": "app",
+      "writeScope": ["src"],
+      "gates": ["unit"]
+    }
+  ]
+}