npm - devcontour-harness - Versions diffs - 0.1.0-alpha.12 → 0.1.0-alpha.13 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +15 -2
package/docs/connectors.md +26 -0
package/docs/quickstart.md +1 -1
package/docs/release-notes/0.1.0-alpha.13.md +91 -0
package/docs/turbo-starter.md +2 -1
package/docs/upgrade.md +14 -14
package/examples/turbo-starter/setup.mjs +9 -2
package/lib/connectors/files.js +2 -0
package/lib/integrations/connector/commands.d.ts +11 -4
package/lib/integrations/connector/commands.js +16 -2
package/lib/integrations/connector/config.d.ts +5 -0
package/lib/integrations/connector/config.js +18 -1
package/lib/integrations/connector/index.d.ts +1 -1
package/lib/integrations/connector/index.js +1 -1
package/lib/integrations/connector/snapshot.d.ts +22 -1
package/lib/integrations/connector/snapshot.js +60 -3
package/lib/integrations/connector/source.d.ts +4 -0
package/lib/integrations/connector/source.js +1 -0
package/package.json +1 -1
package/skills/harness-setup/SKILL.md +191 -69
package/templates/controller-mode/README.md +5 -0

package/README.md CHANGED Viewed

@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
 интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
 и доказательствами.
-> Статус: `0.1.0-alpha.12` — предварительный выпуск (alpha). Договоры
+> Статус: `0.1.0-alpha.13` — предварительный выпуск (alpha). Договоры
 > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
 > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
 > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
 Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
 ```sh
-npm install --save-exact devcontour-harness@0.1.0-alpha.12   # точная версия
+npm install --save-exact devcontour-harness@0.1.0-alpha.13   # точная версия
 # или: npm install --save-exact devcontour-harness@alpha     # текущая alpha
 npx harness --version
 ```
@@ -123,6 +123,19 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
 `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
 Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
+## Выпуск 0.1.0-alpha.13
+Controller mode для задач Relay и установка без лишних вопросов. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.13.md).
+- `tasks[].context` и `contextDir` коннектора: локальные пакеты контекста
+  (оверлей controller-mode) закрепляются в снимке задач Relay.
+- Skill `harness-setup` решает рутинные выборы сам и спрашивает только на
+  развилках (вендоры writer/reviewer, недостающие факты Relay, изоляция,
+  Docker, конфликты с правилами проекта, коммит, запись в Relay, живые
+  вызовы); маршрут для pnpm/Turborepo-монорепо (Turbo Starter): свой
+  профиль, gates из команд проекта, controller mode.
 ## Выпуск 0.1.0-alpha.12
 Skill установки и обновления. Подробно —

package/docs/connectors.md CHANGED Viewed

@@ -109,14 +109,40 @@ CLI: 0 — успех, 2 — неверный вход, 3 — отказ/бло
 | `projectId`           | Ожидаемая идентичность проекта backend; несовпадение блокирует чтение снимка и любые мутации                                                                                                                                                                                                                    |
 | `actor`               | Автор всех записей коннектора                                                                                                                                                                                                                                                                                   |
 | `stateDir`            | Каталог состояния коннектора (относительно файла); без него — `--state`                                                                                                                                                                                                                                         |
+| `contextDir`          | Каталог локальных пакетов контекста `tasks[].context` (относительно файла); по умолчанию `work/context`                                                                                                                                                                                                         |
 | `repository`          | ID репозитория политики (и путь для сверки)                                                                                                                                                                                                                                                                     |
 | `tasks[]`             | Задачи: `ref` (постоянный ID или ключ), роль, `writeScope`, `gates`, сопоставление критериев, обязательные документы                                                                                                                                                                                            |
 | `tasks[].criteria[]`  | Критерий (`id` или точный `title`) → `gate` и `testId` JUnit; `evidence: "gate"` — достаточно прошедшего gate (явный выбор)                                                                                                                                                                                     |
+| `tasks[].context`     | Локальные пакеты контекста поручения — каталоги `<contextDir>/<id>` (например, `controller-mode`); закрепляются в снимке                                                                                                                                                                                        |
 | `completion`          | `complete` — закрыть по правилам backend (по умолчанию в `done`); `review-only` — перевести в `review`/`column` и оставить человеку; `historicalComment` — при конфликте постановки записать явно исторический комментарий                                                                                      |
 | `eligibility.columns` | Колонки, из которых задача допускается к запуску (`done`/`cancelled` — никогда)                                                                                                                                                                                                                                 |
 | `limits`              | Пределы документов и постановки, число повторных чтений, срок владения доставкой                                                                                                                                                                                                                                |
 | `history`             | Запись истории работы (корневая и дочерние сессии)                                                                                                                                                                                                                                                              |
+### Локальные пакеты контекста
+`tasks[].context` добавляет к поручению задачи пакеты из `<contextDir>/<id>` —
+те же каталоги, что у файлового графа: файлы вкладываются в запросы writer и
+reviewer, `references/` закрепляется digest без вложения. Так к задачам Relay
+подключается оверлей controller-mode
+(`templates/controller-mode/`): `"context": ["controller-mode"]`.
+- Пакеты закрепляются в `context.json` снимка; поручение получает
+  `context: [<контекст задачи>, ...пакеты]`. `source-snapshot` и manifest
+  называют их в `localContext` (ID, digest, число файлов и справок, байты).
+- Digest пакетов и их распределение по задачам (какие у какой, в каком
+  порядке) входят в ревизию набора задач: изменённый, новый или перенесённый
+  пакет — новый `source-snapshot`, ревью плана и согласование (`run --source`
+  иначе отказывает `APPROVAL_STALE`). Semantic digest задачи от пакетов не
+  зависит: включение поля или изменение пакета не делает доставку уже
+  принятого результата конфликтом.
+- Нет каталога или пакета — `NOT_READY` до чтения backend; пакет через
+  symlink — `INVALID_INPUT`. `source-check` называет то и другое в `problems`.
+- Пределы контекста (файл, сумма, не больше 30 источников вместе с
+  контекстами задач) проверяются при снимке: превышение — `LIMIT_EXCEEDED`, и
+  задача не допускается к запуску.
+- Без поля снимок, ревизия и digest задачи те же, что в прежних версиях.
 ### Идентичность и снимок
 - Идентичность задачи — `<provider>:<projectId>:<постоянный ID>`; ID поручения

package/docs/quickstart.md CHANGED Viewed

@@ -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.12
+npm install --save-exact devcontour-harness@0.1.0-alpha.13
 npx harness --version
 npx harness doctor
 ```

package/docs/release-notes/0.1.0-alpha.13.md ADDED Viewed

@@ -0,0 +1,91 @@
+# devcontour-harness 0.1.0-alpha.13
+Controller mode для задач Relay и маршрут установки, который спрашивает только
+на развилках. Gates, `maxAttempts`, бюджеты попыток и повторов, правила
+находок, изоляция, принятие target ref и формат состояния не менялись.
+## Что нового
+- **`tasks[].context` и `contextDir` коннектора.** Задача Relay получает,
+  кроме своего контекста, локальные пакеты из `<contextDir>/<id>` (по
+  умолчанию `work/context` рядом с `connector.json`) — например, оверлей
+  controller-mode из `templates/controller-mode/`. Пакет закрепляется в
+  `context.json` снимка теми же правилами, что файловый контекст графа
+  (`references/` — справки без вложения). Digest пакетов и их распределение
+  по задачам входят в ревизию набора задач: изменённый пакет требует нового `source-snapshot` и
+  согласования (`run --source` иначе отказывает `APPROVAL_STALE`). Semantic
+  digest задачи от пакетов не зависит: включение поля или изменение пакета не
+  делает доставку принятого результата конфликтом. Нет каталога или пакета —
+  `NOT_READY` до чтения backend; `source-check` называет его в `problems`
+  ([connectors](../connectors.md#локальные-пакеты-контекста)).
+- **Пределы контекста при снимке.** `source-snapshot` проверяет пределы
+  снимка контекста (размер файла, сумма, не больше 30 источников) и сообщает
+  превышение как `LIMIT_EXCEEDED`, а не только отказом при запуске;
+  `source-check` проверяет пределы локальных пакетов. Вывод
+  `source-snapshot` и manifest называют закреплённые пакеты (`localContext`).
+- **`controllerContext`** (`examples/turbo-starter/setup.mjs`) пересобирает
+  пакет с пустого каталога и не берёт в справки `.harness/` и сам каталог
+  пакета: повторная сборка внутри репозитория не вкладывает копии пакета и
+  не оставляет справки удалённых AGENTS.md. `upstream: null` — сборка для
+  обычного репозитория проекта.
+- **Skill `harness-setup`:**
+  - таблица «решить или спросить»: рутинные выборы (ветка, каталог
+    установки, источник пакета, профиль, gates, согласование, completion)
+    агент делает сам и объясняет в отчёте; спрашивает о вендорах
+    writer/reviewer, ревью тем же вендором, controller mode (оверлей
+    главнее правил продукта), пропуске проверки проекта или CI, недостающих
+    фактах Relay, изоляции, Docker, конфликтах с правилами проекта, коммите,
+    записи в Relay и живых вызовах;
+  - pnpm/Turborepo-монорепо (Turbo Starter): локальный `.harness/profile.json`
+    из команд проекта (`pnpm --filter`), test-gates с JUnit без новых
+    зависимостей или приёмочные проверки в `.harness/acceptance/`, gate
+    детерминизма генерации, защищённые пути, среда с Docker только по
+    согласию;
+  - controller mode: пакет собирается `controllerContext`, в Git не
+    коммитится (`.git/info/exclude`, пересборка в новом клоне) и
+    подключается к файловым графам и к задачам Relay (`tasks[].context`);
+  - при обновлении — предложить новые возможности выпуска, не применяя их.
+## Изменения договора
+Добавления в конфигурацию коннектора: `contextDir` (строка) и
+`tasks[].context` (1–10 ID); в manifest снимка и ответ `source-snapshot` —
+`localContext` (только при пакетах). Без них снимок, ревизия набора, semantic
+digest задачи, digest графа и контекста те же, что в alpha.12. Пакет с именем
+вида ID контекста задачи (`c` + 20 hex) — `INVALID_INPUT`.
+Изменение отказа: корень источника контекста через symlink (в файловом
+графе и в пакетах коннектора) — `INVALID_INPUT` «Контекст не читается через
+symlink» вместо `NOT_READY` «не найден»; symlink внутри источника и раньше
+давал `INVALID_INPUT`.
+## Совместимость
+Формат состояния не менялся: alpha.13 читает всё, что читает alpha.12, а
+alpha.12 — всё, что пишет alpha.13. Конфигурация коннектора с новыми полями
+alpha.12 не принимает (строгая схема). Обновление и откат — по
+[upgrade](../upgrade.md).
+## Проверка выпуска
+`npm run check` (lint, typecheck, schemas, build, весь набор тестов, package
+smoke из установленного архива) на macOS arm64, Node.js 24.3. Тесты
+коннектора на подделке backend (`tests/connector-context.test.ts`):
+- пакет закреплён в снимке и поручении, его байты в контексте попытки
+  writer; поручение принято и доставлено;
+- без поля ревизия набора, digest задачи, графа и контекста совпадают со
+  значениями alpha.12 (golden-тест, сверен с кодом тега);
+- изменённый пакет — `APPROVAL_STALE` до запуска; перенос пакета между
+  задачами и смена порядка — новая ревизия; больше 30 источников —
+  `LIMIT_EXCEEDED`; доставка принятого
+  результата после изменения пакета и после включения поля — не конфликт;
+- нет каталога — отказ без обращений к backend; нет пакета, свой
+  `contextDir`, конфликт имени, symlink-пакет, превышение пределов в снимке
+  и `source-check`, `localContext` в manifest.
+Пересборка `controllerContext` после коммита пакета и удаления AGENTS.md —
+`tests/starter-setup.test.ts`. Тест skill сверяет команды, флаги,
+обязательные аргументы и пути `<pkg>/…` с поставкой. Живые модели и
+настоящие Relay не вызывались; W01 на настоящих Relay для alpha.13 не
+повторялся.

package/docs/turbo-starter.md CHANGED Viewed

@@ -224,7 +224,8 @@ controller. Оверлей `templates/controller-mode/AGENTS.controller.md` v1
   читает живые файлы своего worktree;
 - `context/controller-mode/provenance.json` содержит версию и sha256
   оверлея, baseline SHA и blob каждого product AGENTS.md;
-- в каждом поручении указан `"context": ["controller-mode"]`.
+- в каждом поручении указан `"context": ["controller-mode"]`; для задач
+  Relay — в `tasks[].context` коннектора ([connectors](connectors.md#локальные-пакеты-контекста)).
 Оверлей перечисляет правила, делегированные controller-у: worktree, commit,
 merge, история Relay, `pnpm run setup`, вложенные оркестраторы и `harness`.

package/docs/upgrade.md CHANGED Viewed

@@ -21,20 +21,20 @@
 ## Матрица форматов
-| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6    | Читает 0.1.0-alpha.7 | Читает 0.1.0-alpha.8 | Читает 0.1.0-alpha.9 | Читает 0.1.0-alpha.10 | Читает 0.1.0-alpha.11 | Читает 0.1.0-alpha.12 | Пишет поверх | Примечание                                                                                                                                                                                 |
-| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | -------------------- | -------------------- | -------------------- | --------------------- | --------------------- | --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| standalone `stateVersion: 1` версией alpha.1                                   | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да           | одна база SQLite: документ, события, локальные записи                                                                                                                                      |
-| хост, центральная база                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | данные не переносятся; новые поля необязательны                                                                                                                                            |
-| хост, базы компонентов                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | нужна копия всех баз при остановленных writers                                                                                                                                             |
-| alpha.2 после штатной остановки controller                                     | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да           | роль controller снята — нового поля в состоянии нет                                                                                                                                        |
-| alpha.2 с живой или брошенной ролью controller                                 | **нет**, отказ до записи | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию                                                                                                        |
-| alpha.4 с совместной проверкой                                                 | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию                                                                                                           |
-| alpha.6 standalone с записями ревью нового протокола или доставкой `uncertain` | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | —            | `reviewRound`, `findings[].id/status`, статус доставки `uncertain`; alpha.4/alpha.5 отказывают `STATE_VERSION_UNSUPPORTED` до записи → откат через копию                                   |
-| alpha.6, хост DevContour (адаптер alpha.4)                                     | —                        | —                        | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | адаптер DevContour alpha.4 открывает такое состояние без отказа и пишет роль controller и события; новые поля сохраняются → для отката всё равно копия                                     |
-| alpha.7 с новым `inspection` ревью кода                                        | не проверялось           | не проверялось           | **нет** (строгая схема) | да                   | да                   | да                   | да                    | да                    | да                    | —            | новые значения `source`, `exitCode: null`, `origins`/`context`/`excluded`; строгая схема alpha.6 их не принимает, поведение прежних версий при открытии не проверялось → откат через копию |
-| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи    | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                                                        |
-Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи) и строки alpha.7. alpha.8, alpha.9, alpha.10, alpha.11 и alpha.12 формат состояния не меняют и читают всё, что читает alpha.7. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
+| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6    | Читает 0.1.0-alpha.7 | Читает 0.1.0-alpha.8 | Читает 0.1.0-alpha.9 | Читает 0.1.0-alpha.10 | Читает 0.1.0-alpha.11 | Читает 0.1.0-alpha.12 | Читает 0.1.0-alpha.13 | Пишет поверх | Примечание                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | -------------------- | -------------------- | -------------------- | --------------------- | --------------------- | --------------------- | --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| standalone `stateVersion: 1` версией alpha.1                                   | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | да           | одна база SQLite: документ, события, локальные записи                                                                                                                                      |
+| хост, центральная база                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | данные не переносятся; новые поля необязательны                                                                                                                                            |
+| хост, базы компонентов                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | нужна копия всех баз при остановленных writers                                                                                                                                             |
+| alpha.2 после штатной остановки controller                                     | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | да           | роль controller снята — нового поля в состоянии нет                                                                                                                                        |
+| alpha.2 с живой или брошенной ролью controller                                 | **нет**, отказ до записи | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию                                                                                                        |
+| alpha.4 с совместной проверкой                                                 | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию                                                                                                           |
+| alpha.6 standalone с записями ревью нового протокола или доставкой `uncertain` | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | `reviewRound`, `findings[].id/status`, статус доставки `uncertain`; alpha.4/alpha.5 отказывают `STATE_VERSION_UNSUPPORTED` до записи → откат через копию                                   |
+| alpha.6, хост DevContour (адаптер alpha.4)                                     | —                        | —                        | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | адаптер DevContour alpha.4 открывает такое состояние без отказа и пишет роль controller и события; новые поля сохраняются → для отката всё равно копия                                     |
+| alpha.7 с новым `inspection` ревью кода                                        | не проверялось           | не проверялось           | **нет** (строгая схема) | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | новые значения `source`, `exitCode: null`, `origins`/`context`/`excluded`; строгая схема alpha.6 их не принимает, поведение прежних версий при открытии не проверялось → откат через копию |
+| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи    | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                                                        |
+Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи) и строки alpha.7. alpha.8, alpha.9, alpha.10, alpha.11, alpha.12 и alpha.13 формат состояния не меняют и читают всё, что читает alpha.7. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
 формата до записи проверяют тесты совместимости пакета
 <!-- repo-only -->(`tests/compatibility.test.ts`)<!-- /repo-only -->.

package/examples/turbo-starter/setup.mjs CHANGED Viewed

@@ -34,7 +34,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -257,10 +257,17 @@ export function changeFiles(fixture, patch) {
  */
 export function controllerContext(fixture, dir) {
   const target = join(dir, 'controller-mode');
+  // Пересборка начинается с пустого каталога: справки удалённых AGENTS.md не
+  // остаются, а закоммиченный пакет и .harness/ не попадают в свои же справки.
+  rmSync(target, { recursive: true, force: true });
   mkdirSync(join(target, 'references'), { recursive: true });
   const overlay = readFileSync(join(CONTROLLER_TEMPLATE, 'AGENTS.controller.md'));
   writeFileSync(join(target, 'AGENTS.controller.md'), overlay);
-  const product = git(fixture.repo, ['ls-files', '--', 'AGENTS.md', '**/AGENTS.md'])
+  const inside = relative(fixture.repo, resolve(target));
+  const exclude = [':(exclude).harness/**'];
+  if (inside && !inside.startsWith('..') && !isAbsolute(inside))
+    exclude.push(`:(exclude)${inside.split(sep).join('/')}/**`);
+  const product = git(fixture.repo, ['ls-files', '--', 'AGENTS.md', '**/AGENTS.md', ...exclude])
     .split('\n')
     .filter(Boolean);
   const references = product.map((path) => {

package/lib/connectors/files.js CHANGED Viewed

@@ -71,6 +71,8 @@ export class FileContextSource {
         const base = realpathSync(this.dir);
         const sources = [...new Set(ids)].map((id) => {
             const root = resolve(base, id);
+            if (root.startsWith(base + sep) && existsSync(root) && lstatSync(root).isSymbolicLink())
+                throw new HarnessError('INVALID_INPUT', `Контекст не читается через symlink: ${id}`);
             if (!root.startsWith(base + sep) || !existsSync(root) || !lstatSync(root).isDirectory())
                 throw new HarnessError('NOT_READY', `Источник контекста ${id} не найден в ${this.dir}`);
             const pin = (path) => {

package/lib/integrations/connector/commands.d.ts CHANGED Viewed

@@ -63,6 +63,7 @@ export declare class Connector {
             requiredDocuments: string[];
             repositoryId?: string | undefined;
             gates?: string[] | undefined;
+            context?: string[] | undefined;
         }[];
         completion: {
             mode: "complete" | "review-only";
@@ -85,6 +86,7 @@ export declare class Connector {
             client: string;
         };
         stateDir?: string | undefined;
+        contextDir?: string | undefined;
     } | {
         provider: "relay-v2-cli";
         relay: Record<string, unknown> & {
@@ -115,6 +117,7 @@ export declare class Connector {
             requiredDocuments: string[];
             repositoryId?: string | undefined;
             gates?: string[] | undefined;
+            context?: string[] | undefined;
         }[];
         completion: {
             mode: "complete" | "review-only";
@@ -137,7 +140,10 @@ export declare class Connector {
             client: string;
         };
         stateDir?: string | undefined;
+        contextDir?: string | undefined;
     };
+    /** Каталог пакетов `tasks[].context`: `contextDir` конфигурации, иначе `work/context` рядом с ней. */
+    get contextDir(): string;
     /** Состояние коннектора (создаётся при первой записи). */
     get store(): ConnectorStore;
     /** Только чтение: без создания файла; нет состояния — `undefined`. */
@@ -186,10 +192,6 @@ export declare class Connector {
      * semantic digest: повтор неизменной постановки ничего не меняет.
      */
     snapshot(outDir?: string): Promise<{
-        connector: string;
-        graphId: string;
-        graphDigest: string;
-        contextDigest: string;
         revision: string;
         created: boolean;
         eligible: boolean;
@@ -209,6 +211,11 @@ export declare class Connector {
             manifest: string;
         };
         snapshot: import("./snapshot.ts").BuiltSnapshot;
+        localContext?: import("./snapshot.ts").LocalContextManifest[] | undefined;
+        connector: string;
+        graphId: string;
+        graphDigest: string;
+        contextDigest: string;
     }>;
     /**
      * Перед запуском — свежее чтение: semantic digest обязан совпасть с

package/lib/integrations/connector/commands.js CHANGED Viewed

@@ -1,12 +1,12 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { HarnessError, } from "../../contracts/index.js";
+import { API_VERSION, HarnessError, } from "../../contracts/index.js";
 import { redactor } from "../../environment/redaction.js";
 import { connectorIdOf, loadConfig, orderIdOf, resolveFrom, storeFileOf, } from "./config.js";
 import { RelaySink } from "./delivery.js";
 import { HistoryRecorder } from "./history.js";
 import { createTransportFor } from "./registry.js";
-import { assertEligible, checkIdentity, matchCriterion, readStable, semanticDigest, } from "./snapshot.js";
+import { assertEligible, checkIdentity, contextLimitIssues, localContext, matchCriterion, readStable, semanticDigest, } from "./snapshot.js";
 import { RelayWorkSource } from "./source.js";
 import { redactingTransport, settingsSecrets } from "./redact.js";
 import { ConnectorStore } from "./store.js";
@@ -46,6 +46,10 @@ export class Connector {
     get config() {
         return this.loaded.config;
     }
+    /** Каталог пакетов `tasks[].context`: `contextDir` конфигурации, иначе `work/context` рядом с ней. */
+    get contextDir() {
+        return resolveFrom(this.loaded.baseDir, this.config.contextDir ?? 'work/context');
+    }
     /** Состояние коннектора (создаётся при первой записи). */
     get store() {
         this.storeInstance ??= new ConnectorStore(this.storeFile, { provider: this.config.provider, projectId: this.config.projectId }, this.options.onStoreWrite ? { onWrite: this.options.onStoreWrite } : {});
@@ -64,6 +68,7 @@ export class Connector {
             config: this.config,
             transport: this.transport,
             store: this.store,
+            contextDir: this.contextDir,
         });
     }
     get history() {
@@ -114,6 +119,14 @@ export class Connector {
             return this.checkReport(undefined, false, [message], []);
         }
         const mapping = [];
+        try {
+            const local = await localContext(config, this.contextDir);
+            if (local.length)
+                problems.push(...contextLimitIssues({ apiVersion: API_VERSION, sources: local, missing: [] }));
+        }
+        catch (error) {
+            problems.push(this.redact(error instanceof Error ? error.message : String(error)));
+        }
         try {
             const { reads } = await readStable(this.transport, config.tasks.map((t) => t.ref), config.limits.rereads);
             reads.forEach((read, i) => {
@@ -202,6 +215,7 @@ export class Connector {
             graphId: snapshot.graph.id,
             graphDigest: snapshot.manifest.graphDigest,
             contextDigest: snapshot.manifest.contextDigest,
+            ...(snapshot.manifest.localContext ? { localContext: snapshot.manifest.localContext } : {}),
             revision: snapshot.revision,
             created,
             eligible: snapshot.problems.length === 0,

package/lib/integrations/connector/config.d.ts CHANGED Viewed

@@ -40,6 +40,7 @@ export declare const taskMappingSchema: z.ZodObject<{
         }>>;
     }, z.core.$strict>>>;
     requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    context: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type TaskMapping = z.infer<typeof taskMappingSchema>;
 export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -51,6 +52,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     projectId: z.ZodString;
     actor: z.ZodString;
     stateDir: z.ZodOptional<z.ZodString>;
+    contextDir: z.ZodOptional<z.ZodString>;
     repository: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -72,6 +74,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
             }>>;
         }, z.core.$strict>>>;
         requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        context: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     completion: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
@@ -122,6 +125,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     projectId: z.ZodString;
     actor: z.ZodString;
     stateDir: z.ZodOptional<z.ZodString>;
+    contextDir: z.ZodOptional<z.ZodString>;
     repository: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -143,6 +147,7 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
             }>>;
         }, z.core.$strict>>>;
         requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        context: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     completion: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{

package/lib/integrations/connector/config.js CHANGED Viewed

@@ -57,6 +57,13 @@ export const taskMappingSchema = z.strictObject({
     criteria: z.array(criterionMappingSchema).max(100).default([]),
     /** Документы, без которых запуск блокируется (ID, ключ или имя). Остальные — дополнительные. */
     requiredDocuments: z.array(z.string().min(1).max(200)).max(30).default([]),
+    /**
+     * Локальные пакеты контекста поручения — каталоги `<contextDir>/<id>` (например,
+     * оверлей controller-mode). Закрепляются в снимке вместе с контекстом задачи;
+     * изменение набора или содержимого пакетов — новый снимок и новое
+     * согласование; semantic digest задачи от них не зависит.
+     */
+    context: z.array(idSchema).min(1).max(10).optional(),
 });
 const relaySettings = z.record(z.string(), z.unknown());
 const common = {
@@ -69,6 +76,8 @@ const common = {
      * для процессов, разделяющих этот каталог.
      */
     stateDir: z.string().min(1).max(1000).optional(),
+    /** Каталог пакетов `tasks[].context` (относительно файла конфигурации); по умолчанию `work/context`. */
+    contextDir: z.string().min(1).max(1000).optional(),
     repository: z.strictObject({
         id: idSchema,
         /** Путь репозитория для сверки с политикой (относительно файла конфигурации). */
@@ -161,6 +170,12 @@ export function parseConfig(value, baseDir, file) {
     const dup = refs.find((r, i) => refs.indexOf(r) !== i);
     if (dup)
         throw new HarnessError('INVALID_INPUT', 'source: задача указана дважды: ' + dup);
+    // ID контекста задачи — `c` + 20 hex (contextIdOf): локальный пакет не может его занять.
+    const taken = parsed.data.tasks
+        .flatMap((t) => t.context ?? [])
+        .find((id) => /^c[0-9a-f]{20}$/.test(id));
+    if (taken)
+        throw new HarnessError('INVALID_INPUT', `source: пакет контекста ${taken} совпадает по форме с ID контекста задачи; выберите другое имя`);
     return { config: parsed.data, baseDir, ...(file ? { file } : {}) };
 }
 export function loadConfig(path) {
@@ -204,7 +219,9 @@ export const contextIdOf = (orderId) => 'c' + orderId.slice(1);
 export const graphIdOf = (provider, projectId, taskIds) => 'g' + short([provider, projectId, ...[...taskIds].sort()].join('\n'));
 /** Digest сопоставления задачи: входит в semantic digest — смена mapping требует нового согласования. */
 export const mappingDigest = (config, mapping) => digestOf({
-    mapping: { ...mapping, ref: undefined },
+    // Пакеты контекста — не постановка задачи: их ID и digest входят в ревизию
+    // набора (новое согласование), но доставку принятого результата не меняют.
+    mapping: { ...mapping, ref: undefined, context: undefined },
     repository: config.repository.id,
     completion: config.completion,
 });

package/lib/integrations/connector/index.d.ts CHANGED Viewed

@@ -6,7 +6,7 @@
 export * from './transport.ts';
 export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, type ConnectorConfig, type ConnectorConfigInput, type CriterionMapping, type TaskMapping, type LoadedConfig, } from './config.ts';
 export { ConnectorStore, LeaseLost, type OperationRecord, type OperationStatus, type StepRecord, type StepStatus, type LeaseRecord, type ReceiptRecord, type SnapshotRecord, } from './store.ts';
-export { buildSnapshot, checkIdentity, readStable, semanticDigest, takeSnapshot, assertEligible, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
+export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
 export { RelayWorkSource } from './source.ts';
 export { RelaySink, operationKey, type ReconcileDecision, type SinkOptions } from './delivery.ts';
 export { HistoryRecorder, type SessionLink } from './history.ts';

package/lib/integrations/connector/index.js CHANGED Viewed

@@ -6,7 +6,7 @@
 export * from "./transport.js";
 export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, } from "./config.js";
 export { ConnectorStore, LeaseLost, } from "./store.js";
-export { buildSnapshot, checkIdentity, readStable, semanticDigest, takeSnapshot, assertEligible, } from "./snapshot.js";
+export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, } from "./snapshot.js";
 export { RelayWorkSource } from "./source.js";
 export { RelaySink, operationKey } from "./delivery.js";
 export { HistoryRecorder } from "./history.js";

package/lib/integrations/connector/snapshot.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { HarnessError, type ContextSnapshot, type WorkGraph } from '../../contracts/index.ts';
+import { HarnessError, type ContextSnapshot, type ContextSourceEntry, type WorkGraph } from '../../contracts/index.ts';
 import { type ConnectorConfig, type TaskMapping } from './config.ts';
 import type { ReceiptRecord } from './store.ts';
 import { type CriterionRecord, type RelayTransport, type TaskRead, type TransportIdentity } from './transport.ts';
@@ -84,6 +84,15 @@ export interface SnapshotManifest {
     tasks: TaskManifest[];
     truncated: string[];
     problems: SnapshotProblem[];
+    /** Закреплённые локальные пакеты `tasks[].context`; без них поля нет. */
+    localContext?: LocalContextManifest[];
+}
+export interface LocalContextManifest {
+    id: string;
+    digest: string;
+    files: number;
+    references: number;
+    bytes: number;
 }
 export interface BuiltSnapshot {
     graph: WorkGraph;
@@ -119,12 +128,24 @@ export declare function buildSnapshot(input: {
     rounds: number;
     /** Доверенный receipt этого коннектора для задачи-зависимости вне графа. */
     receiptOf: (orderId: string) => ReceiptRecord | undefined;
+    /** Закреплённые локальные пакеты `tasks[].context` (localContext). */
+    local?: ContextSourceEntry[];
 }): BuiltSnapshot;
+/** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
+export declare function contextLimitIssues(context: ContextSnapshot): string[];
+/**
+ * Локальные пакеты `tasks[].context` из `contextDir`: те же правила, что у
+ * файлового контекста графа (каталог `<contextDir>/<id>`, `references/` —
+ * справки). Нет каталога или пакета — NOT_READY до чтения backend.
+ */
+export declare function localContext(config: ConnectorConfig, contextDir: string | undefined): Promise<ContextSourceEntry[]>;
 /** Прочитать, собрать и проверить идентичность: общий путь `source-snapshot` и `run --source`. */
 export declare function takeSnapshot(input: {
     config: ConnectorConfig;
     transport: RelayTransport;
     receiptOf: (orderId: string) => ReceiptRecord | undefined;
+    /** Абсолютный каталог пакетов `tasks[].context`. */
+    contextDir?: string;
     signal?: AbortSignal;
 }): Promise<BuiltSnapshot>;
 /** Отказ по eligibility/limits: причина и предел в сообщении, без запуска. */

package/lib/integrations/connector/snapshot.js CHANGED Viewed

@@ -1,6 +1,8 @@
-import { API_VERSION, HarnessError, contextDigest, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
+import { existsSync, statSync } from 'node:fs';
+import { API_VERSION, HarnessError, CONTEXT_LIMITS, contextDigest, contextIssues, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
 import { connectorIdOf, contextIdOf, graphIdOf, mappingDigest, orderIdOf, taskIdentity, } from "./config.js";
 import { TransportError, } from "./transport.js";
+import { FileContextSource } from "../../connectors/files.js";
 /** Безопасная причина отказа транспорта при чтении: сеть/CLI — не пустой список. */
 export function readFailure(error, what) {
     if (error instanceof HarnessError)
@@ -124,6 +126,8 @@ export function buildSnapshot(input) {
     const missing = [];
     const prerequisites = new Map();
     const tasks = [];
+    /** Какие локальные пакеты у какой задачи (по порядку): часть ревизии набора. */
+    const packsByTask = [];
     const truncated = [];
     let totalBytes = 0;
     const limits = config.limits;
@@ -331,8 +335,9 @@ export function buildSnapshot(input) {
             ...(mapping.gates ? { gates: mapping.gates } : {}),
             requirements: [],
             contracts: [],
-            context: [entry.id],
+            context: [entry.id, ...(mapping.context ?? [])],
         });
+        packsByTask.push([identityOf, mapping.context ?? []]);
         tasks.push({
             ref: mapping.ref,
             id: task.id,
@@ -367,6 +372,15 @@ export function buildSnapshot(input) {
         connector,
         tasks: tasks.map((t) => [t.identity, t.semanticDigest]),
         prerequisites: prereqs,
+        // Без локальных пакетов ревизия та же, что до их появления. С ними —
+        // содержимое пакетов и их распределение по задачам: перенос пакета между
+        // задачами или смена порядка — тоже новое согласование.
+        ...(input.local?.length || packsByTask.some(([, ids]) => ids.length)
+            ? {
+                context: (input.local ?? []).map((s) => [s.id, s.digest]),
+                contextBy: [...packsByTask].sort(([a], [b]) => (a < b ? -1 : 1)),
+            }
+            : {}),
     });
     const joined = `${config.provider}:${config.projectId}:${taskIds.join('+')}`;
     const graph = workGraphSchema.parse({
@@ -380,7 +394,15 @@ export function buildSnapshot(input) {
         orders,
         prerequisites: prereqs,
     });
-    const context = { apiVersion: API_VERSION, sources, missing };
+    const context = {
+        apiVersion: API_VERSION,
+        sources: [...sources, ...(input.local ?? [])],
+        missing,
+    };
+    // Пределы снимка контекста проверяются здесь, а не только при запуске:
+    // source-snapshot и source-check называют их как отказ eligibility.
+    for (const issue of contextLimitIssues(context))
+        problems.push({ code: 'LIMIT_EXCEEDED', taskId: '', key: 'context', message: issue });
     const manifest = {
         version: 1,
         provider: config.provider,
@@ -398,11 +420,45 @@ export function buildSnapshot(input) {
         tasks,
         truncated,
         problems,
+        ...(input.local?.length ? { localContext: input.local.map(localManifest) } : {}),
     };
     return { graph, context, manifest, revision, problems };
 }
+const CONTEXT_SOURCES_MAX = 30;
+/** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
+export function contextLimitIssues(context) {
+    const issues = contextIssues(context);
+    if (context.sources.length > CONTEXT_SOURCES_MAX)
+        issues.push(`Источников контекста ${context.sources.length} при пределе ${CONTEXT_SOURCES_MAX} (задачи и локальные пакеты)`);
+    return issues.map((i) => /больше предела/.test(i)
+        ? `${i} (fileBytes=${CONTEXT_LIMITS.fileBytes}, totalBytes=${CONTEXT_LIMITS.totalBytes})`
+        : i);
+}
+const localManifest = (s) => ({
+    id: s.id,
+    digest: s.digest,
+    files: s.files.length,
+    references: s.references.length,
+    bytes: [...s.files, ...s.references].reduce((n, f) => n + f.bytes, 0),
+});
+/**
+ * Локальные пакеты `tasks[].context` из `contextDir`: те же правила, что у
+ * файлового контекста графа (каталог `<contextDir>/<id>`, `references/` —
+ * справки). Нет каталога или пакета — NOT_READY до чтения backend.
+ */
+export async function localContext(config, contextDir) {
+    const ids = [...new Set(config.tasks.flatMap((t) => t.context ?? []))].sort();
+    if (!ids.length)
+        return [];
+    if (!contextDir)
+        throw new HarnessError('INVALID_INPUT', 'source: tasks[].context требует каталог пакетов (contextDir)');
+    if (!existsSync(contextDir) || !statSync(contextDir).isDirectory())
+        throw new HarnessError('NOT_READY', `Каталог пакетов контекста ${contextDir} не найден (tasks[].context: ${ids.join(', ')})`);
+    return (await new FileContextSource(contextDir).snapshot(ids)).sources;
+}
 /** Прочитать, собрать и проверить идентичность: общий путь `source-snapshot` и `run --source`. */
 export async function takeSnapshot(input) {
+    const local = await localContext(input.config, input.contextDir);
     const identity = await checkIdentity(input.transport, input.config, input.signal);
     const { reads, rounds } = await readStable(input.transport, input.config.tasks.map((t) => t.ref), input.config.limits.rereads, input.signal);
     return buildSnapshot({
@@ -411,6 +467,7 @@ export async function takeSnapshot(input) {
         reads,
         rounds,
         receiptOf: input.receiptOf,
+        ...(local.length ? { local } : {}),
     });
 }
 /** Отказ по eligibility/limits: причина и предел в сообщении, без запуска. */

package/lib/integrations/connector/source.d.ts CHANGED Viewed

@@ -19,12 +19,16 @@ export declare class RelayWorkSource implements WorkSource {
         config: ConnectorConfig;
         transport: RelayTransport;
         store: ConnectorStore;
+        /** Абсолютный каталог пакетов `tasks[].context`. */
+        contextDir?: string;
     };
     readonly id: string;
     constructor(options: {
         config: ConnectorConfig;
         transport: RelayTransport;
         store: ConnectorStore;
+        /** Абсолютный каталог пакетов `tasks[].context`. */
+        contextDir?: string;
     });
     /** Снимок без проверки eligibility (для предпросмотра и диагностики). */
     snapshot(signal?: AbortSignal): Promise<BuiltSnapshot>;

package/lib/integrations/connector/source.js CHANGED Viewed

@@ -26,6 +26,7 @@ export class RelayWorkSource {
             config: this.options.config,
             transport: this.options.transport,
             receiptOf: (orderId) => this.options.store.receipts(orderId).at(-1),
+            ...(this.options.contextDir ? { contextDir: this.options.contextDir } : {}),
             ...(signal ? { signal } : {}),
         });
     }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "devcontour-harness",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
   "type": "module",
   "license": "MIT",

package/skills/harness-setup/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: harness-setup
-description: Install, configure or upgrade devcontour-harness for a new or existing npm/pnpm Git repository — ask the setup questions once (project, branch, install location, package source, writer and reviewer models, approval, task source such as files or Relay), install the exact version inside the project (`.harness-tools/`) or outside it, run `harness init`, record the decisions and hand over to the `harness` skill; upgrade an installed version with a state copy and a compatibility check.
+description: Install, configure or upgrade devcontour-harness for a new or existing npm/pnpm Git repository, including pnpm/Turborepo monorepos such as Turbo Starter and task sources such as Relay — decide every routine choice yourself from the repository, ask the user only at real forks (which vendor writes and which accepts, a missing Relay fact, isolation or Docker, rule conflicts, commits, writes to Relay, live model calls), install the exact version in `.harness-tools/`, run `harness init`, and hand over to the `harness` skill; upgrade an installed version with a state copy and a compatibility check.
 ---
 # Harness setup
@@ -18,52 +18,51 @@ replaces or relaxes them.
 Every `harness` command prints one JSON envelope on stdout (`ok` with `data`,
 or `error`); exit codes: 0 success, 2 invalid input, 3 refusal or block,
 4 infrastructure. Below `$H` is the installed CLI:
-`H=<tooldir>/node_modules/.bin/harness`.
+`H=<tooldir>/node_modules/.bin/harness`, and `<pkg>` is
+`<tooldir>/node_modules/devcontour-harness`.
 Modes: **install** (first setup), **upgrade** (change the installed version),
 **check** (report what is installed; read only). Pick the mode from the
 request; when the repository already has `.harness/` and a pinned or
 installed `$H`, it is upgrade or check, not install.
-## Install
+## Decide or ask
+Decide everything you can from the repository and the defaults below, and
+report each decision with its reason at the end; the user overrides any of
+them by saying so. Ask only at a fork — a choice that changes who is trusted,
+what leaves the machine, what is spent or which project rule gives way — and
+ask all open forks of a step in one round (multiple choice where the host
+supports it).
+| Choice                     | Default (decide yourself)                                                                                     | Ask when                                                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Writer and reviewer vendor | —                                                                                                             | always: which of `claude` / `codex` writes; the other one reviews and accepts                                                                         |
+| Same vendor for review     | never                                                                                                         | only one runtime is installed, or the user asked for it                                                                                               |
+| Models and effort          | runtime defaults                                                                                              | the user named models                                                                                                                                 |
+| Branch                     | new branch `harness-setup` from the current branch; an existing `harness/accepted` is reported and left alone | the working tree is not clean                                                                                                                         |
+| Install location           | `<repo>/.harness-tools`                                                                                       | the user asked for a directory outside the repository                                                                                                 |
+| Package source             | npm `@alpha` resolved to the exact version                                                                    | the user gave a version or a tarball                                                                                                                  |
+| Stack profile              | built-in by lockfile; a local `.harness/profile.json` when the project does not have its scripts (below)      | —                                                                                                                                                     |
+| Gates                      | derived from the project's own commands (step 6), each reported with its command                              | a check the project or its CI runs would be left out, or no command can prove behaviour without new dependencies                                      |
+| Plan approval              | `agent` (`init` default)                                                                                      | the user wants to approve plans themselves (`operator`)                                                                                               |
+| Task source                | Relay when the repository or the request names it, otherwise graph files                                      | both are plausible                                                                                                                                    |
+| Relay connection           | discovered from the repository and environment                                                                | a fact is missing: endpoint or binary/config, `projectId`, which tasks                                                                                |
+| Relay completion           | `review-only` (a human closes the task)                                                                       | the user wants `complete`                                                                                                                             |
+| Controller mode            | —                                                                                                             | the product AGENTS.md tells agents to manage worktrees, commits, merges or Relay history: the overlay then takes precedence over those rules (step 9) |
+| OS isolation               | on                                                                                                            | prepare or gates fail inside the sandbox (store, network, Docker socket)                                                                              |
+| Docker environment         | none                                                                                                          | gates need a database or other service                                                                                                                |
+| Project rule conflicts     | —                                                                                                             | a project rule forbids what setup creates (for example new `.md` files: `.harness/README.md`)                                                         |
+| Commit, Relay writes, runs | —                                                                                                             | always confirm: committing the setup, `run --source` / `source-deliver` / `source-reconcile`, any live `run` or `review-plan`                         |
-### 0. Ask once
-Ask everything in one round (a multiple-choice question per item where the
-host supports it); offer the default first. Do not ask what the repository
-already answers: detect the lockfile, `packageManager`, an existing
-`.harness/`, the current branch and which of `claude` / `codex` are installed
-first. Whether a runtime is signed in is not detectable without a model call:
-the user confirms it.
-| #   | Question                        | Options (default first)                                                                      | Becomes                                                               |
-| --- | ------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| 1   | Repository                      | existing path / new project at a path                                                        | step 2                                                                |
-| 2   | Branch for the setup            | new branch `harness-setup` / current branch                                                  | step 3; never the name `harness` (it clashes with `harness/accepted`) |
-| 3   | Install location                | inside the project `.harness-tools/` / outside, in a tool directory                          | `<tooldir>` of step 4                                                 |
-| 4   | Package source                  | npm `@alpha` resolved to an exact version / npm exact version / local `.tgz` with its sha256 | step 4                                                                |
-| 5   | Writer runtime                  | `claude` / `codex`                                                                           | `init --writer`; the reviewer is the other vendor                     |
-| 6   | Models and effort               | runtime defaults / explicit `model` (and `effort` for codex) for writer and reviewer         | step 6                                                                |
-| 7   | Reviewer of the writer's vendor | no (`different-vendor`) / yes for code and contract review, stated explicitly                | step 6                                                                |
-| 8   | Plan approval                   | `agent` (the reviewer approves) / `operator` (a human runs `approve`)                        | step 6                                                                |
-| 9   | Task source                     | graph files in `.harness/work/` / Relay v1 (HTTP) / Relay-2 (CLI)                            | step 7                                                                |
-| 10  | Commit the setup                | commit on the setup branch / leave uncommitted                                               | step 8                                                                |
-For Relay also ask: the v1 endpoint, or the absolute Relay-2 binary, the
-absolute `relay.config.json` / `relay.workspace.json` and the workspace
-project; `projectId`; `actor` (default `harness-controller`); the task refs
-and, per task, its write scope when it is narrower than the whole
-repository; the columns a task may start from; `completion.mode`
-(`review-only` for the first run, or `complete`).
-The answers are the user's decisions. Do not change them later without
-asking.
+## Install
 ### 1. Preconditions
 Node.js ≥ 24.3, `git`, `npm` (or `pnpm` for a pnpm project) and the runtime
-CLIs the answers name (`claude --version`, `codex --version`). A missing or
-signed-out runtime is the user's to fix; a live run is impossible without it.
+CLIs (`claude --version`, `codex --version`). Whether a runtime is signed in
+is not detectable without a model call: the user confirms it. A missing or
+signed-out runtime is the user's to fix.
 The package manager version is checked exactly: the built-in profiles pin
 one (`npm-ci` pins npm `11.4.2`), and `package.json#packageManager`
@@ -75,9 +74,8 @@ project is the user's decision.
 **Existing.** It must be the top level of a Git repository with at least one
 commit and exactly one lockfile: `package-lock.json` (profile `npm-ci`) or
-`pnpm-lock.yaml` (profile `pnpm-frozen`). Both or none is decided by the user
-(`--profile`, or a local `.harness/profile.json` passed as
-`--profile ./.harness/profile.json`).
+`pnpm-lock.yaml` (profile `pnpm-frozen`). With both or none, write a local
+profile (step 6).
 **New.** Create it only with the user's consent, at the path they gave:
@@ -106,11 +104,11 @@ a gate.
 ### 3. Branch
 `git status` must be clean (ask the user about local changes; never stash or
-discard them yourself). Then `git switch -c <branch>`.
+discard them yourself). Then `git switch -c harness-setup`.
 `run` creates `refs/heads/harness/accepted` from the `HEAD` of the main
 checkout when that ref does not exist yet. Keep the setup branch checked out,
-with the setup committed (step 8), until the first `run`: otherwise
+with the setup committed (step 11), until the first `run`: otherwise
 `harness/accepted` starts from a commit without it. When `harness/accepted`
 already exists, report its SHA and leave it alone. Accepted work lands in
 `harness/accepted`, not in the setup branch; merging it anywhere is the
@@ -169,14 +167,71 @@ $H doctor
 Never install the package into the project's own dependencies as part of this
 route, and never put the execution state inside the repository.
-### 5. `harness init`
+### 5. Read the project
+Before choosing gates read: the root and package `package.json` scripts, the
+lockfile, `pnpm-workspace.yaml`, `turbo.json`, every `AGENTS.md`, CI
+workflows (they show which commands the project trusts), code generators
+(OpenAPI, SDK, Prisma) and Relay traces (`relay.config.json`,
+`relay.workspace.json`, `.artifacts/relay/`, Relay commands in AGENTS.md).
+### 6. Stack profile and gates
+**A built-in profile fits** when the project already has the scripts it
+calls (`npm-ci` / `pnpm-frozen`: `check`, and `test` writing JUnit to
+`.reports/junit.xml`). Then skip to step 7.
+**Otherwise write `.harness/profile.json`** (`<pkg>/schemas/stack-profile.schema.json`)
+and pass `--profile ./.harness/profile.json` to `init`. This is the usual
+case for a pnpm/Turborepo monorepo; Turbo Starter is the worked example
+(`<pkg>/docs/turbo-starter.md`, `<pkg>/examples/turbo-starter/policy.json`):
+- `prepare`: `pnpm install --frozen-lockfile`.
+- check gates (`kind: check`): the project's own type and build commands per
+  package, called directly — `pnpm --filter <package> run check-types`,
+  `… run build`, with `dependsOn` where one needs another's output. Prefer
+  the per-package commands a root script runs when the root script also
+  does work that cannot run in a worktree (for example an environment check
+  that fails on the pinned Node); that keeps every check the root script
+  makes. Leaving out a check the project or its CI runs is the user's
+  decision. Never call `turbo run` without `--force` (a cache hit proves
+  nothing), and `pnpm exec turbo` only with an exactly pinned `turbo`.
+- test gates (`kind: test`, at least one, with
+  `report: { type: junit, path: .artifacts/junit/<gate>.xml }`): an existing
+  test command that can write JUnit without new dependencies (Node's test
+  runner `--test-reporter=junit --test-reporter-destination=…`, Vitest's
+  built-in `junit` reporter). When the project has none, or its AGENTS.md
+  forbids tests in product code, put acceptance tests in
+  `.harness/acceptance/*.test.mjs` run by `node --test`, as the example does.
+  When no command can prove behaviour without adding a dependency, ask.
+- code generation (OpenAPI, SDK): a test gate that runs the project's pinned
+  generator and fails on any difference in the generated paths
+  (`<pkg>/examples/turbo-starter/harness/acceptance/generation.test.mjs`).
+  Generated outputs are not `generatedPaths` (that list means "protected");
+  orders that change generated code list the outputs in their write scope.
+  `generatedPaths` is only for ignored outputs nobody edits (Prisma client).
+- `protectedPaths`: lockfile, every `package.json`, `pnpm-workspace.yaml`,
+  `turbo.json`, `.npmrc`, `scripts/`, `infra/`, CI, every `AGENTS.md`,
+  generator inputs and configuration, `.harness/`, `.harness-tools/`.
+- `toolchain`: the package manager version from `packageManager`, and
+  `node: ">=24.3"`.
+- `environment.values` for variables the commands need to stay local
+  (for example `DOTENV_CONFIG_PATH: /dev/null`, `CHECKPOINT_DISABLE: 1`);
+  secrets only by name in `environment.secrets`, never their values.
+A gate that is red on the current base stays: fixing the base is a separate
+first work order. List the gates with the command each one runs in the
+report.
+### 7. `harness init`
 ```sh
 $H init --repository <repo> --writer <claude|codex> --plan
 $H init --repository <repo> --writer <claude|codex>
 ```
-The first call writes nothing: read `data.files`, `data.conflicts`,
+Add `--profile ./.harness/profile.json` with a local profile. The first call
+writes nothing: read `data.files`, `data.conflicts`,
 `data.toolchain.problems`, `data.facts` and `data.manifest.paths.state`, and
 resolve every conflict or problem with the table of the `harness` skill
 (step 3) before the second call. `init` is create-only: `.harness/.gitignore`,
@@ -184,9 +239,9 @@ resolve every conflict or problem with the table of the `harness` skill
 `.harness/policy.json`. The state lives outside the repository
 (`HARNESS_STATE_HOME`, `XDG_STATE_HOME` or `~/.local/state/devcontour-harness`).
-### 6. Runtimes and approval
+### 8. Runtimes, approval, isolation
-Edit `.harness/policy.json` only as the answers require:
+Edit `.harness/policy.json` only as the decisions require:
 - models: `model` on `roles.<role>.writer` and on `review.code.reviewer`,
   `review.plan.reviewer`, `review.contract.reviewer`;
@@ -200,9 +255,13 @@ Edit `.harness/policy.json` only as the answers require:
   `content-differs` on `policy.json`. When the user wants it anyway, say so
   and let them decide;
 - operator approval: top-level `"approvalMode": "operator"`;
-- with the version pin committed inside the project: add `.harness-tools/` to
-  `repositories[0].protectedPaths`, so no work order can change the tool it
-  is checked by.
+- isolation: keep `isolation.mode: os`. When `doctor` or a first `prepare`
+  shows the sandbox blocking the package store, the network or the Docker
+  socket, show the diagnosis and ask between `isolation.domains` and
+  `isolation.mode: none`;
+- with the version pin committed inside the project: `.harness-tools/` in
+  `repositories[0].protectedPaths` (already there when the local profile
+  lists it).
 Never remove or weaken anything `init` wrote. Keep the writer runtime as
 `init` wrote it: a different writer vendor is a new `init --writer` decision.
@@ -221,18 +280,67 @@ non-codex runtime, the reviewer vendor rule, unknown gates) run in
 for the first graph before any review or run, and fix the policy, not the
 check, when it fails.
-### 7. Task source
+**Services.** When gates need a database or another service, ask before
+using Docker. With a yes, copy `<pkg>/examples/turbo-starter/harness/`
+(`compose-bridge.mjs`, `compose.acceptance.yml`, `env/`) into `.harness/`,
+adapt the compose model to the project and add `repositories[0].lifecycle`
+(setup, ready, teardown) and the secret names as in
+`<pkg>/docs/turbo-starter.md`; gates that need the service run through
+`node .harness/compose-bridge.mjs exec -- <command>`.
+### 9. Controller mode
+When the product AGENTS.md tells an agent to create worktrees, commit, merge,
+move tasks or keep Relay history itself, the harness controller does those
+operations instead, and the worker needs the controller-mode overlay
+(`<pkg>/templates/controller-mode/README.md`). The overlay takes precedence
+over those product rules, so ask first: show the rules it overrides and say
+that the overlay text names Turbo Starter commands (`pnpm worktree:create`,
+`pnpm rest-api-sdk:generate`) as examples. Without a yes, keep controller
+mode off; the harness still refuses a worker commit (`scope-violation`).
+With a yes, build the pack from the committed AGENTS.md files:
+```sh
+node --input-type=module -e "
+import { controllerContext } from '<pkg>/examples/turbo-starter/setup.mjs';
+import { execFileSync } from 'node:child_process';
+const repo = '<repo>';
+const baselineSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo }).toString().trim();
+controllerContext({ repo, baselineSha, upstream: null }, repo + '/.harness/work/context');
+"
+```
+It writes `.harness/work/context/controller-mode/` (the unchanged overlay,
+`references/` with the product AGENTS.md files, `provenance.json`); a rebuild
+starts from an empty directory and never lists `.harness/`. The pack is not
+committed to the repository (some projects forbid new `.md` files): keep it
+out of Git and rebuild it in a fresh clone with the same command. Its
+`provenance.json` records the `HEAD` it was built on, so a rebuild on another
+commit is a new pack digest and the next Relay snapshot needs a new approval
+even when no AGENTS.md changed.
+```sh
+grep -qxF '.harness/work/context/controller-mode/' <repo>/.git/info/exclude \
+  || echo '.harness/work/context/controller-mode/' >> <repo>/.git/info/exclude
+```
+File graphs list `"context": ["controller-mode"]` on every order; Relay tasks
+list it in `tasks[].context` of the connector (step 10). A changed AGENTS.md
+or overlay means rebuilding the pack, and the next snapshot needs a new
+approval; a result already accepted is still delivered.
+### 10. Task source
 **Graph files.** Nothing more to configure; the `harness` skill plans the
 first graph.
-**Relay.** Write `.harness/connector.json` from `docs/connectors.md` of the
-installed package ("Конфигурация"):
+**Relay.** Write `.harness/connector.json` from `<pkg>/docs/connectors.md`
+("Конфигурация"):
 - `"version": 1` and `"provider": "relay-v1-http"` or `"relay-v2-cli"`,
   always explicit — never guessed from a binary named `relay`;
-- `projectId` and `actor` at the top level; `repository.id` is the policy
-  repository id (`app` after `init`);
+- `projectId` and `actor` (`harness-controller`) at the top level;
+  `repository.id` is the policy repository id (`app` after `init`);
 - adapter settings nested under `relay`: v1 `relay.endpoint`; Relay-2
   absolute `relay.binary` and `relay.config`, `relay.project` for a workspace,
   `relay.env` that may set `RELAY_HOME` (and on macOS `DYLD_LIBRARY_PATH` to
@@ -240,9 +348,12 @@ installed package ("Конфигурация"):
 - `tasks[]`: `ref`; `role` and `gates` only from `data.facts` of `init`;
   `writeScope` (required) = the role's `writePaths` from the facts, or, when
   the role has none, `["."]` (the whole repository) or the narrower paths the
-  user named; `criteria` mapped to a gate and a JUnit `testId`;
-- `completion: { "mode": "review-only" }` (or `"complete"`) and
-  `eligibility.columns` from the answers;
+  task names (with generated outputs when it changes them); `criteria` mapped
+  to a gate and a JUnit `testId`; `"context": ["controller-mode"]` with
+  controller mode (step 9) — the pack is read from `contextDir`, by default
+  `work/context` next to `connector.json`;
+- `completion: { "mode": "review-only" }` unless the user chose `complete`;
+  `eligibility.columns` from the project's board; `history.enabled: true`;
 - no `stateDir` (pass `--state <manifest.paths.state>`), no secret values.
 Checks that do not write to Relay:
@@ -250,30 +361,36 @@ Checks that do not write to Relay:
 ```sh
 $H source-check --source <repo>/.harness/connector.json --policy <repo>/.harness/policy.json --state <state>
 $H source-snapshot --source <repo>/.harness/connector.json --policy <repo>/.harness/policy.json --state <state> --out <dir outside the repo>
+$H validate --graph <dir outside the repo>/graph.json --policy <repo>/.harness/policy.json --context <dir outside the repo>/context.json
 ```
 `source-check` is read only. `source-snapshot` reads Relay but records the
 snapshot in the connector state under `--state` and writes `graph.json`,
-`context.json` and `manifest.json` to `--out`. `run --source`,
+`context.json` and `manifest.json` to `--out`; its output names the pinned
+local packs (`localContext`) and a context over the limits as
+`LIMIT_EXCEEDED`. `run --source`,
 `source-deliver` and `source-reconcile` write to Relay: run them only after
 the user says so.
-### 8. Commit
+### 11. Commit
 With the user's yes: commit on the setup branch `.harness/.gitignore`,
-`.harness/README.md`, `.harness/policy.json`, `.harness/connector.json` (when
-present) and, for an npm source inside the project,
+`.harness/README.md`, `.harness/policy.json`, `.harness/profile.json`,
+`.harness/connector.json`, `.harness/acceptance/` and the bridge files when
+present, and, for an npm source inside the project,
 `.harness-tools/.gitignore`, `.harness-tools/package.json`,
 `.harness-tools/package-lock.json`. Never `project.json`, `node_modules/` or
-the state. Do not push or merge.
+the state or the controller-mode pack. Do not push or merge.
-### 9. Report and hand over
+### 12. Report and hand over
-Report: installed version (and the tarball sha256), `doctor`, the decisions
-of the manifest (profile, writer, reviewer, state path), the policy edits,
-the connector check, the commit SHA. Then continue with the `harness` skill:
-brief → `plan-request` → draft → `plan-check` → `validate` → `run`. A live
-`run` or `review-plan` calls paid models: start it when the user asks.
+Report: installed version (and the tarball sha256), `doctor`, every decision
+of the table with its reason, the gates with their commands, the policy
+edits, controller mode, the connector check and snapshot (`graphId`,
+`graphDigest`, eligibility per task), the commit SHA. Then continue with the
+`harness` skill: brief → `plan-request` → draft → `plan-check` → `validate`
+→ `run` (for Relay: `review-plan` and `run --source`). A live `run` or
+`review-plan` calls paid models: start it when the user asks.
 ## Upgrade
@@ -320,6 +437,9 @@ otherwise in step 7.
      graphs may need plan review or approval again (`explain` names it).
    - `$H validate --graph <graph> --policy <repo>/.harness/policy.json` for
      every `.harness/work/*.json` graph.
+   - Read the release notes for new options the setup should use (for
+     example `tasks[].context` of the connector for controller mode) and
+     propose them; do not apply them unasked.
 8. **Resume.** `$H resume --state <state>`, then `run` as before. Attempts that
    were active at the stop are not continued with old tokens; recovery either
    accepts a saved integration SHA or ends the attempt.
@@ -341,8 +461,10 @@ and `$H --version`, or a missing `node_modules/` (restore with `npm ci`, step
 ## Don'ts
-- Do not choose for the user: location, source, runtimes, models, the vendor
-  rule, approval mode, task source and commits are their answers.
+- Do not ask what the repository answers, and do not decide a fork of the
+  table for the user: the vendors, a reviewer of the writer's vendor,
+  controller mode, a left-out project check, isolation, Docker, project rule
+  conflicts, commits, writes to Relay and live runs are theirs.
 - Do not install into the project's dependencies, edit its `package.json` or
   lockfile (except when bootstrapping a new project with consent), or put the
   state inside the repository.

package/templates/controller-mode/README.md CHANGED Viewed

@@ -27,6 +27,11 @@ not a file committed to the target repository. Some projects forbid new
 4. Add `"context": ["controller-mode"]` to every order of the graph. Writer
    and reviewers then see the same pinned bytes, and a changed overlay
    requires a new plan approval.
+   For tasks read from Relay, list the pack in the connector instead:
+   `"context": ["controller-mode"]` on each entry of `tasks[]`, with the
+   directory at `<contextDir>/controller-mode` (`contextDir` defaults to
+   `work/context` next to `connector.json`). The snapshot pins it the same
+   way, and a changed overlay needs a new snapshot and approval.
 5. Protect the product AGENTS.md files and the harness setup through the
    policy's `protectedPaths`. The worker cannot change the rules it runs
    under.