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

package/README.md

@@ -5,16 +5,17 @@ Headless-движок исполнения инженерных поручени
 интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
 и доказательствами.
 
-> Статус: `0.1.0-alpha.11` — предварительный выпуск (alpha). Договоры
+> Статус: `0.1.0-alpha.13` — предварительный выпуск (alpha). Договоры
 > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
 > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
 > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
 > потребителями, свойствами и корпусом, совместной проверкой репозиториев и
 > явным режимом одного вендора.
 
-Пакет включает встроенные профили стеков (`profiles/`), skill
-`skills/harness/SKILL.md` и шаблоны политики, графа и инструкции агентам
-(`templates/`).
+Пакет включает встроенные профили стеков (`profiles/`), skills
+`skills/harness/SKILL.md` (работа с поручениями) и
+`skills/harness-setup/SKILL.md` (установка, первая настройка и обновление
+версии), шаблоны политики, графа и инструкции агентам (`templates/`).
 
 ## Требования
 
@@ -27,7 +28,7 @@ Headless-движок исполнения инженерных поручени
 Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
 
 ```sh
-npm install --save-exact devcontour-harness@0.1.0-alpha.11   # точная версия
+npm install --save-exact devcontour-harness@0.1.0-alpha.13   # точная версия
 # или: npm install --save-exact devcontour-harness@alpha     # текущая alpha
 npx harness --version
 ```
@@ -35,6 +36,11 @@ npx harness --version
 Выпуски публикуются под тегом `alpha`; ставьте точную версию или `@alpha`,
 а не версию по умолчанию без тега.
 
+Чтобы не менять зависимости и lockfile существующего проекта, пакет ставят в
+отдельный каталог инструментов — снаружи репозитория или в `.harness-tools/`
+внутри него ([standalone](docs/standalone.md#установка), skill
+[harness-setup](skills/harness-setup/SKILL.md)).
+
 Из локального архива `devcontour-harness-<version>.tgz` (поддерживаемый
 способ без registry):
 
@@ -117,6 +123,31 @@ 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 установки и обновления. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.12.md).
+
+- `skills/harness-setup/SKILL.md` — агент один раз спрашивает решения первой
+  настройки (новый или существующий проект, ветка, каталог установки —
+  `.harness-tools/` в проекте или снаружи, источник пакета, writer и reviewer
+  с моделями, согласование, источник задач: файлы или Relay), ставит точную
+  версию, выполняет `init` и обновляет версию с копией state и проверкой
+  совместимости. Движок, договоры и формат состояния не менялись.
+
 ## Выпуск 0.1.0-alpha.11
 
 Профили в форме хоста. Подробно —
@@ -226,6 +257,7 @@ alpha.5 не читает; прежний DevContour его открывает
 ## Документация
 
 - [Быстрый старт по шагам](docs/quickstart.md)
+- [Установка, первая настройка и обновление версии — skill harness-setup](skills/harness-setup/SKILL.md)
 - [Самостоятельный проект: init, планирование (plan-request, plan-check), explain, capabilities, проекции](docs/standalone.md)
 - [Архитектура и границы доверия](docs/architecture.md)
 - [Договоры: входы, выходы, порты, ошибки, CLI](docs/contracts.md)

package/docs/architecture.md

@@ -74,8 +74,8 @@ RunResult (SHA, evidence, ограничения) -> ResultSink
 Таблица перечисляет каталоги `src/`. Git-операции — worktrees, snapshots,
 проверка области, candidate/integration, CAS и recovery — отдельного каталога
 не образуют: они в `engine` (`runner.ts`, `joint-runner.ts`), `control`
-(`base-move.ts`) и `verification`. Поставляемый skill с инструкциями и
-шаблонами лежит в корневом каталоге пакета `skills/`; исполняемые гарантии
+(`base-move.ts`) и `verification`. Поставляемые skills лежат в корневом
+каталоге пакета `skills/`, шаблоны — в `templates/`; исполняемые гарантии
 остаются в движке.
 
 Модули `setup`, `planning`, `explain`, `projections`, `catalog` и разрешение
@@ -413,9 +413,10 @@ runtime-граф пакета.
 
 ## Профили, skills и шаблоны
 
-Встроенные профили (`profiles/`), skill (`skills/harness/SKILL.md`) и шаблоны
-(`templates/`: политика, граф, инструкция агентам репозитория) входят в пакет.
-Skill и шаблоны только объясняют использование: движок, runner и проверки их
+Встроенные профили (`profiles/`), skills (`skills/harness/SKILL.md` — работа
+с поручениями, `skills/harness-setup/SKILL.md` — установка, первая настройка
+и обновление версии) и шаблоны (`templates/`: политика, граф, инструкция
+агентам репозитория) входят в пакет. Skills и шаблоны только объясняют использование: движок, runner и проверки их
 не читают, и удаление каталога skills не отключает ни gates, ни ревью, ни
 область записи, ни fencing — это проверяет smoke установленного архива.
 Профиль — вход для сборки политики, а не исполняемый объект: разрешение не

package/docs/connectors.md

@@ -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

@@ -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.11
+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.12.md

@@ -0,0 +1,66 @@
+# devcontour-harness 0.1.0-alpha.12
+
+Skill установки, первой настройки и обновления версии. Движок, CLI, договоры
+`v1alpha1`, политика, профили и формат состояния не менялись; gates,
+`maxAttempts`, бюджеты попыток и повторов, правила находок, изоляция и
+принятие target ref — прежние.
+
+## Что нового
+
+- **`skills/harness-setup/SKILL.md`** — маршрут для агента пользователя:
+  - один раунд вопросов: существующий или новый проект, ветка подготовки,
+    каталог установки (`.harness-tools/` внутри проекта или каталог
+    снаружи), источник пакета (npm `@alpha`, сведённый к точной версии,
+    точная версия или архив с sha256), writer и reviewer, модели и effort,
+    ревью тем же вендором (только явным «да»), режим согласования плана,
+    источник задач (файлы графа, Relay v1, Relay-2), коммит подготовки;
+  - новый проект: Git, `package.json` со scripts `check` и `test` (JUnit в
+    `.reports/junit.xml`) и lockfile — только с согласия пользователя;
+  - установка в проект: версию закрепляют `.harness-tools/package.json` и
+    `package-lock.json`, `node_modules/` не коммитится, каталог добавляется в
+    `protectedPaths` политики; из архива — каталог целиком в
+    `.git/info/exclude`;
+  - `init` и правки политики по ответам: `model`, `effort` (только для
+    codex), reviewer того же вендора для ревью кода и контракта
+    (`same-vendor-allowed`), `approvalMode`; проверка `doctor --policy`
+    (схема, runtime, toolchain), `init --plan` без конфликтов и `validate`
+    первого графа (перекрёстные проверки политики);
+  - `connector.json` для Relay и проверки без записи в Relay
+    (`source-check`, `source-snapshot`);
+  - обновление: остановка writers, копия state, проверка копии новой
+    версией, установка, `doctor --state`, `init --plan` (изменённый профиль,
+    перенос репозитория или версия API — решение человека; manifest
+    пересоздаётся с прежним state, политика не перегенерируется), `validate`
+    графов, `resume`; откат по [upgrade](../upgrade.md);
+  - восстановление закреплённой версии в новом клоне — `npm ci --prefix
+.harness-tools`.
+- `skills/harness/SKILL.md` по-прежнему ведёт работу с поручениями; новый
+  skill передаёт ему управление после подготовки. В нём уточнены каталог
+  установки (снаружи или `.harness-tools/`) и причины `content-differs` на
+  `project.json` после обновления или переноса.
+
+## Документация
+
+- [standalone](../standalone.md): установка вне проекта или в
+  `.harness-tools/`, закрепление версии файлом, обновление.
+- [architecture](../architecture.md): состав поставляемых skills.
+- [upgrade](../upgrade.md): столбец alpha.12 в матрице форматов.
+
+## Совместимость
+
+Формат состояния не менялся: alpha.12 читает всё, что читает alpha.11, а
+alpha.11 — всё, что пишет alpha.12. Обновление и откат — по
+[upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` (lint, typecheck, schemas, build, весь набор тестов, package
+smoke из установленного архива) на macOS arm64, Node.js 24.3. Тест skill
+сверяет с договором CLI каждую команду маршрута: команду, флаги и
+обязательные аргументы полных вызовов; smoke установленного архива требует
+оба skill. Маршрут установки в `.harness-tools/` пройден вручную на свежем
+npm-репозитории с опубликованной alpha.11: `init --plan`, `init`, правки
+политики, `doctor --policy`, отказ `validate` для `effort` не у codex,
+пересоздание manifest с прежним state. Живые модели не вызывались;
+проверка DevContour для alpha.12 не повторялась (движок не менялся,
+[проверенные версии](../compatibility-versions.md) относятся к alpha.11).

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

@@ -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/standalone.md

@@ -4,20 +4,41 @@
 без внешнего хоста: пользователь называет репозиторий, цель и ограничения,
 остальное агент получает от `harness init`, а план составляет сам через
 `harness plan-request` и `harness plan-check`. Пошаговый маршрут для агента —
-skill [`skills/harness/SKILL.md`](../skills/harness/SKILL.md).
+skill [`skills/harness/SKILL.md`](../skills/harness/SKILL.md); установку,
+первую настройку и обновление версии ведёт skill
+[`skills/harness-setup/SKILL.md`](../skills/harness-setup/SKILL.md).
 
-## Установка вне проекта
+## Установка
 
 Пакет ставится в отдельный каталог инструментов, а не в зависимости проекта:
-`package.json` и lockfile проекта не меняются.
+`package.json` и lockfile проекта не меняются. Каталог — снаружи
+репозитория или внутри него, в `.harness-tools/`.
 
 ```sh
-npm install --prefix <tooldir> --omit=dev --ignore-scripts ./devcontour-harness-<version>.tgz
+npm install --prefix <tooldir> --save-exact --omit=dev --ignore-scripts devcontour-harness@<version>
+# или из архива: npm install --prefix <tooldir> --omit=dev --ignore-scripts ./devcontour-harness-<version>.tgz
 H=<tooldir>/node_modules/.bin/harness
 $H --version
 $H doctor
 ```
 
+Внутри проекта (`<tooldir>` = `<repo>/.harness-tools`) версию закрепляют
+`.harness-tools/package.json` и `package-lock.json`: их коммитят вместе с
+`.harness/`, а `node_modules/` исключает `.harness-tools/.gitignore`. Чтобы
+поручение не могло изменить инструмент, которым его проверяют, каталог
+добавляют в `protectedPaths` политики. Установка из архива записывает в
+`package.json` локальный путь `file:` — такой каталог целиком исключают через
+`.git/info/exclude`. Worktrees попыток создаются из Git, поэтому
+неотслеживаемый каталог инструментов в них не попадает. Состояние исполнения
+в любом случае остаётся вне репозитория.
+
+Обновление — смена закреплённой версии в том же каталоге по процедуре
+[upgrade](upgrade.md): остановка writers, копия state, проверка копии новой
+версией, установка, `doctor --state`, `init --plan`, `validate` графов,
+`resume`. Новая версия не перегенерирует политику: если изменился встроенный
+профиль, `init --plan` сообщает `content-differs` на `project.json`, и решение
+принимает человек.
+
 ## `harness init`
 
 ```sh

package/docs/turbo-starter.md

@@ -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

@@ -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 | Пишет поверх | Примечание                                                                                                                                                                                 |
-| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | -------------------- | -------------------- | -------------------- | --------------------- | --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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.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

@@ -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

@@ -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

@@ -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

@@ -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,