devcontour-harness 0.1.0-alpha.25 → 0.1.0-alpha.27

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 (80) hide show
  1. package/README.md +16 -2
  2. package/docs/architecture.md +59 -0
  3. package/docs/compatibility.md +25 -11
  4. package/docs/connectors.md +72 -3
  5. package/docs/contracts.md +60 -24
  6. package/docs/release-notes/0.1.0-alpha.26.md +35 -0
  7. package/docs/release-notes/0.1.0-alpha.27.md +36 -0
  8. package/docs/review-protocol.md +16 -2
  9. package/docs/toolchains.md +83 -0
  10. package/docs/upgrade.md +10 -0
  11. package/lib/agents/cli-adapter.d.ts +6 -0
  12. package/lib/agents/cli-adapter.js +12 -2
  13. package/lib/agents/review-probe.d.ts +5 -0
  14. package/lib/agents/review-probe.js +29 -9
  15. package/lib/agents/schemas.d.ts +4 -0
  16. package/lib/agents/schemas.js +3 -1
  17. package/lib/cli.js +22 -5
  18. package/lib/contracts/cli.d.ts +184 -1
  19. package/lib/contracts/cli.js +102 -2
  20. package/lib/contracts/failure.js +1 -1
  21. package/lib/contracts/policy.d.ts +30 -0
  22. package/lib/contracts/policy.js +23 -0
  23. package/lib/contracts/published.d.ts +8 -0
  24. package/lib/contracts/review.d.ts +69 -0
  25. package/lib/contracts/review.js +29 -14
  26. package/lib/contracts/work.d.ts +6 -0
  27. package/lib/contracts/work.js +13 -12
  28. package/lib/control/harness.d.ts +12 -0
  29. package/lib/control/harness.js +4 -0
  30. package/lib/control/review.js +14 -2
  31. package/lib/engine/joint-runner.js +34 -1
  32. package/lib/engine/runner.d.ts +29 -0
  33. package/lib/engine/runner.js +207 -5
  34. package/lib/engine/worktree-cleanup.d.ts +131 -0
  35. package/lib/engine/worktree-cleanup.js +520 -0
  36. package/lib/environment/bounded-read.d.ts +12 -0
  37. package/lib/environment/bounded-read.js +40 -0
  38. package/lib/environment/isolation.d.ts +1 -0
  39. package/lib/environment/isolation.js +2 -1
  40. package/lib/environment/os-tools.d.ts +4 -2
  41. package/lib/environment/os-tools.js +4 -2
  42. package/lib/environment/process.d.ts +5 -0
  43. package/lib/environment/process.js +40 -17
  44. package/lib/environment/resources.d.ts +9 -0
  45. package/lib/environment/resources.js +24 -0
  46. package/lib/index.d.ts +1 -0
  47. package/lib/index.js +1 -0
  48. package/lib/integrations/connector/commands.d.ts +37 -8
  49. package/lib/integrations/connector/commands.js +61 -8
  50. package/lib/integrations/connector/config.d.ts +37 -0
  51. package/lib/integrations/connector/config.js +37 -5
  52. package/lib/integrations/connector/delivery.js +17 -1
  53. package/lib/integrations/connector/index.d.ts +2 -2
  54. package/lib/integrations/connector/index.js +1 -1
  55. package/lib/integrations/connector/snapshot.d.ts +10 -8
  56. package/lib/integrations/connector/snapshot.js +78 -8
  57. package/lib/integrations/connector/source.d.ts +8 -2
  58. package/lib/integrations/connector/source.js +32 -6
  59. package/lib/integrations/connector/store.d.ts +1 -1
  60. package/lib/integrations/connector/store.js +11 -6
  61. package/lib/integrations/connector/summary.d.ts +6 -0
  62. package/lib/integrations/connector/summary.js +5 -0
  63. package/lib/integrations/connector/testing.js +18 -0
  64. package/lib/integrations/relay-v1/index.js +6 -4
  65. package/lib/integrations/relay-v2/protocol.js +8 -6
  66. package/lib/profiles/resolve.d.ts +6 -0
  67. package/lib/toolchains/inspect.d.ts +1 -1
  68. package/lib/toolchains/inspect.js +29 -1
  69. package/lib/toolchains/probe.d.ts +16 -0
  70. package/lib/toolchains/probe.js +20 -0
  71. package/lib/verification/confirm.d.ts +3 -1
  72. package/lib/verification/confirm.js +26 -4
  73. package/lib/verification/dependencies.d.ts +3 -0
  74. package/lib/verification/dependencies.js +11 -0
  75. package/lib/verification/dependency-store.d.ts +117 -0
  76. package/lib/verification/dependency-store.js +811 -0
  77. package/lib/verification/gates-at.js +18 -0
  78. package/lib/verification/gates.js +24 -7
  79. package/package.json +2 -2
  80. package/schemas/execution-policy.schema.json +34 -0
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.25` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.27` — предварительный выпуск (alpha). Договоры
9
9
  > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
10
10
  > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
11
11
  > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
28
28
  Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
29
29
 
30
30
  ```sh
31
- npm install --save-exact devcontour-harness@0.1.0-alpha.25 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.27 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -99,6 +99,7 @@ git rev-parse refs/heads/harness/accepted # совпадает с data.result.
99
99
  | `status / events / result --state D` | Чтение без побочных эффектов |
100
100
  | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
101
  | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
+ | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
102
103
  | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
103
104
  | `doctor` | Версии, runtime, sandbox, совместимость состояния |
104
105
 
@@ -123,6 +124,19 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
123
124
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
124
125
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
125
126
 
127
+ ## Выпуск 0.1.0-alpha.27
128
+
129
+ Хранилище зависимостей pnpm в политике, команда `worktree-cleanup` для
130
+ деревьев завершённых попыток и более дешёвый поиск оставшихся процессов.
131
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.27.md).
132
+
133
+ ## Выпуск 0.1.0-alpha.26
134
+
135
+ Базовая линия коннектора для зависимостей, закрытых до подключения harness;
136
+ `source-snapshot` работает с пакетами контекста; первая ошибка компилятора
137
+ сохраняется в итоге gate; zod 4.6.7 и пределы вывода runtime. Подробно —
138
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.26.md).
139
+
126
140
  ## Выпуск 0.1.0-alpha.25
127
141
 
128
142
  Native reviewer получает явное `previous: []` при пустой истории находок;
@@ -195,6 +195,61 @@ runtime-граф пакета.
195
195
  записываются туда же. `Harness.cleanup(runId)` повторяет teardown по
196
196
  сохранённым `environment.json` и затем убирает деревья, повторный вызов —
197
197
  `nothing-pending`.
198
+ - **Деревья закончившихся попыток.** Попытка убирает свои деревья сама; после
199
+ падения процесса или отказа удаления они остаются. `harness worktree-cleanup
200
+ --state <каталог> [--dry-run]` (`Harness.cleanupWorktrees`) убирает их, и
201
+ правило у него одно: в сомнении дерево остаётся, а отказ назван.
202
+ - Остаются ветки попыток, коммиты, достижимые из ref общего репозитория, и
203
+ артефакты. Вершина, которую держат только `refs/worktree`, `refs/bisect` или
204
+ `refs/rewritten`, не считается достижимой: они исчезают вместе с деревом, и
205
+ её коммиты собрал бы gc. Такая вершина — отказ.
206
+ - Неподтверждённые правки сначала сохраняются патчем
207
+ `uncommitted-<дерево>[-N].patch` в артефактах попытки. Уже лежащий патч не
208
+ перезаписывается. Патч применяется `git apply --index` поверх вершины; до
209
+ удаления проверено, что он даёт то же дерево.
210
+ - Игнорируемые файлы (`.env`, зависимости, сборка) патч **не сохраняет**: они
211
+ исчезают вместе с деревом, а их число и верхние пути перечислены в поле
212
+ `ignored` ответа, в том числе при `--dry-run`. Dry run не пишет ни состояние,
213
+ ни артефакты, ни индекс дерева.
214
+ - Отказывают поимённо (`reason`): идущая попытка (`active`), последняя попытка
215
+ незакрытой работы (`recoverable`), незавершённая очистка (`cleanup-pending`,
216
+ сначала `cleanup --run`), нечитаемая запись очистки
217
+ (`cleanup-unreadable`), дерево без попытки (`unknown-attempt`), подменённый
218
+ `.git` (`untrusted`), вложенный репозиторий где угодно в дереве, включая
219
+ игнорируемое и `node_modules`, и gitlink индекса (`embedded-repository`),
220
+ недостижимая вершина (`unreachable-head`), отличие действующего `.gitignore`
221
+ от вершины или правило `info/exclude`, скрывающее путь в дереве
222
+ (`ignore-rules-changed`), признаки
223
+ assume-unchanged и skip-worktree (`hidden-changes`), игнорируемый файл, добавленный в индекс через `git add -f`
224
+ и отсутствующий в вершине (`staged-ignored`), проиндексированная версия,
225
+ отличная и от вершины, и от файла дерева (`staged-differs`; индекс, равный
226
+ файлу, правки не теряет), настроенный clean-фильтр
227
+ на пути дерева (`clean-filter`), дерево под `git worktree lock`
228
+ (`worktree-locked`), имя пути не в UTF-8 (`undecodable-path`), каталог только
229
+ для чтения (`read-only-path`), обход дерева, упёршийся в предел или в отказ
230
+ чтения (`scan-limit`, `scan-failed`), патч, не прошедший проверку
231
+ (`patch-unusable`).
232
+ - Правила `core.excludesFile` только показываются в `ignored` и не отказывают:
233
+ они не принадлежат попытке, и обычно это глобальные настройки человека.
234
+ - Перед самым удалением вершина, статус и дерево правок сверяются с тем, на чём
235
+ основано решение, и отличие даёт `tree-changed`; патч строится от той же
236
+ закреплённой вершины, что и в записи. Узкое окно остаётся: запись после сверки
237
+ (или во время удаления) не будет замечена, поэтому команду запускают, когда в
238
+ деревьях никто не работает.
239
+ - Отказ git посреди удаления — `failed` с `removalStarted`: `registered` и
240
+ `treePresent` говорят, что осталось, а часть файлов могла уже исчезнуть. Запись
241
+ `worktree-cleanup-<дерево>.json` в артефактах хранит указатель на патч и
242
+ пишется до удаления: сигнала «git начал удалять» нет. Следующий запуск называет
243
+ такое дерево `removal-incomplete` с тем же `patch` и `record` и не трогает его.
244
+ Выйти из этого состояния: разобрать остаток дерева вручную, при необходимости
245
+ убрать его (`git worktree prune` снимет регистрацию) и удалить файл `record`;
246
+ дерево в порядке — после удаления `record` следующий запуск проверит его
247
+ заново. Дерево на диске без регистрации и без записи — `not-registered`.
248
+ - Одновременно идёт один запуск на каталог состояния: второй получает
249
+ `NOT_READY`. Замок умершего процесса снимается сам; пустой замок и замок с
250
+ живым PID остаются, а ошибка называет файл, который надо удалить, когда
251
+ запуска нет. Замок сверяет PID, поэтому каталог состояния должен принадлежать
252
+ одному пространству PID.
198
253
  - **Покрытие gates.** `uncoveredGates` засчитывает только evidence попыток под
199
254
  текущим основанием политики: тот же ID gate с другой командой — другая
200
255
  проверка.
@@ -630,6 +685,10 @@ executable. Live smoke — отдельный opt-in с явно заданны
630
685
  Закрытие соседних деревьев запрещает чтение их содержимого. Оно не скрывает
631
686
  само существование пути: на macOS разные ответы ENOENT/EPERM могут раскрыть
632
687
  этот факт. Это ограничение песочницы, а не гарантия конфиденциальности имён.
688
+ - **Хранилище зависимостей.** Необязательно (`repositories[].dependencyStore`). Seed собирается
689
+ только из lockfile целевой ветки, в песочнице проверок и в каталоге без файлов проекта; лежит в
690
+ закрытом месте, закреплён вне своего дерева и в checkout попадает клоном со сверкой байтов копии.
691
+ Обратного пути из checkout нет. Подробно — в [toolchains](toolchains.md#хранилище-зависимостей).
633
692
  - **Git хоста над деревом проверки.** Каждый вызов git хоста сначала сверяет,
634
693
  куда git придёт: файл `.git` дерева, созданного `worktree add`, не изменён;
635
694
  gitdir и общий каталог лежат вне дерева и согласованы; `commondir`/`gitdir`
@@ -148,17 +148,19 @@ Standalone-хост использует `digestOf` (SHA-256 каноничес
148
148
 
149
149
  ## Сохраняемые форматы
150
150
 
151
- | Что | Правило |
152
- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
- | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
154
- | Типы событий журнала | Прежние строки, см. `transactionKinds` |
155
- | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
156
- | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
157
- | Receipt среды | `environment.json` `version: 1` |
158
- | Отчёт свойств, договор проверки, корпус | `version: 1` |
159
- | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
160
- | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения |
161
- | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
151
+ | Что | Правило |
152
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
+ | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
154
+ | Типы событий журнала | Прежние строки, см. `transactionKinds` |
155
+ | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
156
+ | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
157
+ | Receipt среды | `environment.json` `version: 1` |
158
+ | Отчёт свойств, договор проверки, корпус | `version: 1` |
159
+ | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
160
+ | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
161
+ | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
162
+ | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
163
+ | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
162
164
 
163
165
  ## Переменные окружения gates
164
166
 
@@ -174,6 +176,17 @@ Gates, шаги подготовки и проверки потребителе
174
176
  `HARNESS_*` с теми же значениями. Оба пространства резервирует controller:
175
177
  политика не может задать переменные с этими префиксами.
176
178
 
179
+ Если у репозитория объявлено `dependencyStore`, переменную `npm_config_store_dir` с путём к хранилищу
180
+ этого checkout получают шаги `prepare`, `dependencyBuild` снимка, gates фазы, gates совместной
181
+ проверки и `teardown`; она заменяет значение из `environment` политики. Не получают её шаги `setup` и
182
+ `ready` (идут раньше), исполнитель и проверки ревьюера: их окружение строится отдельно. Переменная
183
+ задаётся и при промахе, когда `.pnpm-store` создан в дереве. Она не задаётся при `isolation.mode: none`,
184
+ занятом пути `.pnpm-store`, менеджере, который не найден, с неопределённой версией или версией вне
185
+ проверенного диапазона, нечитаемом `package.json`, при превышении любого предела (`maxBytes`, файлов
186
+ seed, элементов checkout, размера lockfile) и при отказе записи в дерево: там окружение и дерево как
187
+ без хранилища. Исключение: если новый lockfile упёрся в предел, а прежний seed подходит, он
188
+ используется как частичное попадание, и переменная задаётся.
189
+
177
190
  ## Что меняется намеренно
178
191
 
179
192
  | Изменение | Следствие |
@@ -182,6 +195,7 @@ Gates, шаги подготовки и проверки потребителе
182
195
  | Reviewer задаётся правилом | `different-vendor` по умолчанию; `same-vendor-allowed` включается явно |
183
196
  | Токены вне журнала | Исправление утечки: прежде `run.claimed` и `run.recovered` записывали в журнал попытку целиком, с fencing-токеном. Новые события пишутся без токенов; при выдаче старых событий наружу (CLI, HTTP, RunEvent) токены удаляются. Историю базы физически не переписываем |
184
197
  | История находок ревью | Reviewer называет состояние прежних находок; прежние попытки читаются без статусов; ревью кода ведёт историю находок поручения с ID controller, находки записей alpha.5 получают детерминированный ID (review-protocol.md) |
198
+ | Пределы ответа runtime | Действуют на границе приёма (contracts.md): схемы состояния, `schemas/*.schema.json` и digest политики не менялись, `storedReviewResultSchema` читает прежние `review.json`. Хост, разбирающий ответы через `reviewResultSchema`, получает новый предел |
185
199
 
186
200
  ## Состояние standalone
187
201
 
@@ -39,6 +39,7 @@ npx harness approve --state ../state --subject <graphId> --digest <graphDigest>
39
39
  # С --source внешние предпосылки (зависимости, выполненные через этот
40
40
  # коннектор) допускаются по решению источника (trusts) и доступности SHA в
41
41
  # target ref — те же правила, что у run; без --source доверенных receipt нет.
42
+ # Так же допускаются зависимости из baseline (см. «Базовая линия»).
42
43
  # В approvalMode: agent ревью плана выполняется в шаге 5 автоматически.
43
44
 
44
45
  # 5. Запуск: задачи перечитываются, semantic digest сверяется с закреплённым
@@ -113,6 +114,7 @@ CLI: 0 — успех, 2 — неверный вход, 3 — отказ/бло
113
114
  | `repository` | ID репозитория политики (и путь для сверки) |
114
115
  | `tasks[]` | Задачи: `ref` (постоянный ID или ключ), роль, `writeScope`, `gates`, сопоставление критериев, обязательные документы |
115
116
  | `tasks[].criteria[]` | Критерий (`id` или точный `title`) → `gate` и `testId` JUnit; `evidence: "gate"` — достаточно прошедшего gate (явный выбор) |
117
+ | `baseline` | Зависимости, закрытые до внедрения harness и принятые человеком: `sha`, `tasks`, `reason` (см. «Базовая линия») |
116
118
  | `tasks[].context` | Локальные пакеты контекста поручения — каталоги `<contextDir>/<id>` (например, `controller-mode`); закрепляются в снимке |
117
119
  | `completion` | `complete` — закрыть по правилам backend (по умолчанию в `done`); `review-only` — перевести в `review`/`column` и оставить человеку; `historicalComment` — при конфликте постановки записать явно исторический комментарий |
118
120
  | `eligibility.columns` | Колонки, из которых задача допускается к запуску (`done`/`cancelled` — никогда) |
@@ -138,11 +140,77 @@ reviewer, `references/` закрепляется digest без вложения.
138
140
  принятого результата конфликтом.
139
141
  - Нет каталога или пакета — `NOT_READY` до чтения backend; пакет через
140
142
  symlink — `INVALID_INPUT`. `source-check` называет то и другое в `problems`.
143
+ - Пакет вне договора источника контекста (больше 30 файлов или 60 справок,
144
+ имя файла с `*`, `?`, `:` и т. п.) — `LIMIT_EXCEEDED` в `problems` снимка и
145
+ `source-check`: запуск отказывает до согласования, а не после него.
141
146
  - Пределы контекста (файл, сумма, не больше 30 источников вместе с
142
147
  контекстами задач) проверяются при снимке: превышение — `LIMIT_EXCEEDED`, и
143
148
  задача не допускается к запуску.
144
149
  - Без поля снимок, ревизия и digest задачи те же, что в прежних версиях.
145
150
 
151
+ ### Базовая линия
152
+
153
+ В существующем проекте история закрыта вручную: receipt этого коннектора у неё
154
+ нет и получить его задним числом нельзя, поэтому задача, зависящая от такой
155
+ истории, не запускается (`DEPENDENCY_UNPROVEN`). Человек принимает такие
156
+ зависимости явно:
157
+
158
+ ```json
159
+ {
160
+ "baseline": {
161
+ "sha": "4f2c9a1e7b3d5c806e1f2a9d4b7c3e5f60a1b2c3",
162
+ "tasks": ["PRODUCT-1", "PRODUCT-2"],
163
+ "reason": "Closed by hand before the harness was adopted"
164
+ }
165
+ }
166
+ ```
167
+
168
+ - `sha` — полный SHA коммита (40 hex), `tasks` — точные ключи задач backend,
169
+ `reason` — непустая причина. Шаблонов, даты отсечения и общего переключателя
170
+ нет; лишнее поле, короткий SHA, повтор ключа или задача самой конфигурации —
171
+ `INVALID_INPUT`.
172
+ - Завершённая зависимость вне графа без receipt и с ключом в `tasks` становится
173
+ обычной предпосылкой: `resultSha` = `sha`, репозиторий — репозиторий
174
+ зависимой задачи, `receipt: {kind: 'trusted', issuer, digest}`, где digest —
175
+ запись базовой линии. Если у зависимости есть настоящий receipt, действует
176
+ он. Незавершённая остаётся `DEPENDENCY_UNFINISHED`, не указанная —
177
+ `DEPENDENCY_UNPROVEN`. Одна зависимость у задач разных репозиториев —
178
+ отказ: базовая линия — один коммит.
179
+ - `trusts` принимает такую предпосылку, только если digest и SHA совпадают с
180
+ **загруженной сейчас** конфигурацией, а backend подтверждает, что ключ — та
181
+ самая задача (чтение задачи; ошибка backend — отказ, а не «нет записи»).
182
+ Движок, как и для любой предпосылки, проверяет доступность SHA в target ref.
183
+ - Любая правка `baseline` меняет ревизию набора задач, даже если запись не
184
+ использована: `run --source` по прежнему снимку отказывает `APPROVAL_STALE`,
185
+ нужны новые `source-snapshot`, ревью плана и согласование. Возврат к прежней
186
+ редакции (постановки или `baseline`) тоже снимается `source-snapshot`: запись
187
+ снимка остаётся прежней (`created: false`), но снова становится последней.
188
+ Semantic digest задачи не меняется: доставка принятого результата конфликтом
189
+ не становится.
190
+ - Происхождение видно: `proof: 'baseline'` у зависимости и `baseline` в
191
+ manifest, в ответах `source-snapshot`, `run --source` и `source-status`,
192
+ строка «Зависимости без доказательства» в итоге для задачи. Предпосылка
193
+ графа сама происхождение не несёт, поэтому `explain` его не показывает.
194
+
195
+ **Что это доказывает.** Только то, что указанный коммит есть в target ref и что
196
+ человек записал своё решение. Что работа задачи действительно входит в этот
197
+ коммит, никто не проверял: SHA общий для всех ключей, gates и ревью по нему не
198
+ запускались. Это решение оператора, а не receipt.
199
+
200
+ **Кто может её изменить.** С `baseline` файл конфигурации обязан лежать вне
201
+ репозиториев политики или внутри их `protectedPaths`: `.harness/connector.json`
202
+ при политике из `harness init` подходит (`.harness/` защищён). Иначе
203
+ `review-plan --source` и `run --source` отказывают `NOT_READY`, а `source-check`
204
+ с `--policy` называет это в `problems`. Ссылка на файл разрешается до проверки.
205
+ Runner отклоняет результат попытки, меняющий защищённый путь, а при
206
+ `isolation.mode: "os"` запись вне рабочего дерева запрещена и самому процессу.
207
+ Защита действует против писателя поручения, а не против того, кто запускает
208
+ harness: controller с доступом к файлу может его изменить, и при
209
+ `approvalMode: agent` человек такую правку не согласует. При `isolation.mode:
210
+ "none"` запрет записи вне дерева держится только на самом runtime. Конфигурация,
211
+ переданная библиотеке объектом, и прямой `Harness.run({ source })` мимо
212
+ `Connector.run` этой проверки не проходят: там за файл отвечает вызывающий код.
213
+
146
214
  ### Идентичность и снимок
147
215
 
148
216
  - Идентичность задачи — `<provider>:<projectId>:<постоянный ID>`; ID поручения
@@ -164,12 +232,13 @@ reviewer, `references/` закрепляется digest без вложения.
164
232
  manifest (`truncated`) либо опускаются с записью в `missing` снимка.
165
233
  - Eligibility проверяется отдельно от digest: `done`/`cancelled`, колонка вне
166
234
  `eligibility.columns`, незавершённая зависимость, зависимость в `done` без
167
- receipt этого коннектора. Колонка, в которую задачу перевела наша
235
+ receipt этого коннектора и без записи в `baseline`. Колонка, в которую задачу перевела наша
168
236
  подтверждённая доставка той же постановки, повтор не блокирует.
169
237
  - Статус `done` зависимости — не доказательство: предпосылка зависимой
170
238
  задачи появляется только из receipt доставки этого коннектора (издатель —
171
- ID коннектора, digest сверяется с его состоянием), и движок дополнительно
172
- проверяет доступность result SHA в target ref.
239
+ ID коннектора, digest сверяется с его состоянием) или из явной записи
240
+ человека в `baseline`, и движок дополнительно проверяет доступность SHA в
241
+ target ref.
173
242
 
174
243
  ## Доставка: протокол и гарантии
175
244
 
package/docs/contracts.md CHANGED
@@ -87,7 +87,11 @@ SHA-256 канонического JSON (`canonicalJson`: ключи по пор
87
87
  Доверие к `trusted` решает `WorkSource.trusts`: `Harness.run({ source })`
88
88
  спрашивает источник графа (его `id` обязан совпасть с `graph.source.connector`);
89
89
  без источника доверенных receipt нет. В обоих случаях движок проверяет, что
90
- result SHA доступен в target ref.
90
+ result SHA доступен в target ref. Коннектор задач выдаёт `trusted` и для
91
+ явной записи человека (`baseline`, см. [connectors.md](connectors.md)): форма
92
+ предпосылки та же, происхождение (`proof: 'receipt' | 'baseline'`) записано в
93
+ manifest снимка и в необязательном поле `baseline` ответов `source-snapshot`,
94
+ `source-status` и `run --source`.
91
95
 
92
96
  ### ExecutionPolicy
93
97
 
@@ -108,6 +112,25 @@ result SHA доступен в target ref.
108
112
 
109
113
  Переменные `HARNESS_*` и `DEVCONTOUR_*` политика задать не может.
110
114
 
115
+ `repositories[].dependencyStore` — необязательное хранилище зависимостей
116
+ репозитория: `{manager: 'pnpm', lockfile, maxBytes, timeoutMs}`. Умолчания:
117
+ `pnpm-lock.yaml`, 8 ГиБ, 600 000 мс. Без поля поведение и digest политики прежние.
118
+ С полем harness сам держит seed по lockfile `targetRef` и разворачивает его в
119
+ каждый checkout: попытка, integration, потребители, `runGatesAt`, проверка
120
+ примера, снимки с `dependencyBuild` и совместная проверка, где `prepare` нет.
121
+ Проекту не нужны ни свой скрипт, ни шаг `prepare`, ни запись в `.gitignore`;
122
+ gate установки остаётся обычным `pnpm install --frozen-lockfile`.
123
+ Подробности и граница доверия — [toolchains](toolchains.md#хранилище-зависимостей).
124
+
125
+ Квитанция `dependency-store.json` лежит в артефактах фазы: `outcome`
126
+ (`hit` — lockfile checkout равен lockfile seed; `partial` — seed другого
127
+ lockfile, установка докачивает разницу; `miss` — обычная установка), `seed`,
128
+ `mode` (`clone` или `copy`), `built`, `files`, `bytes`, `durationMs`, `reason`,
129
+ `refused[]`. Попытка получает этап `dependency-store` в `timings`. Экспорт:
130
+ `materializeStore`, `dependencyStoreRoot`, типы `StoreContext`, `StoreReceipt`. `StoreContext.deadline` — момент окончания времени фазы, `phaseMs` — полная длина её предела: сборка и ожидание чужой сборки занимают не больше трети остатка.
131
+ Исключение `materializeStore` бросает только при отмене переданного `signal`. Коды `doctor`:
132
+ предупреждения `LOCKFILE_MISSING`, `TOOL_MISSING`, `DEPENDENCY_STORE`.
133
+
111
134
  `policyDigest(policy)` — digest загруженной политики целиком: им сверяются
112
135
  применённая политика (`control.appliedPolicy`) и запрос операции
113
136
  `control.reconfigure`. `executionDigest(policy)` — digest исполнительной
@@ -324,6 +347,17 @@ Runtime возвращает сырой ответ; движок разбира
324
347
  аддитивное поле `reviewRound`, находки — `id`/`status`, ссылки результата —
325
348
  `review`. Правила — [docs/review-protocol.md](review-protocol.md).
326
349
 
350
+ Ответ runtime ограничен на границе приёма. В `reviewResultSchema` — не больше
351
+ 500 элементов в `findings` и в `previous` (`REVIEW_ITEMS_LIMIT`; те же
352
+ `maxItems` объявляет wire-схема CLI runtime); файл ответа codex — не больше
353
+ 4 МиБ (`CODEX_RESULT_LIMIT`), читается с границей, без перехода по symlink, а
354
+ файл больше предела удаляется: он не прошёл маскирование. Сверх предела — обычный
355
+ отказ: у reviewer кода ошибка протокола `schema`, у исполнителя класс `unknown`
356
+ без автоматического повтора, у ревью плана и контракта — `RUNTIME_UNAVAILABLE`
357
+ с причиной. Записанное прежними версиями читается
358
+ без этих пределов: `review.json` — `storedReviewResultSchema`, а `ReviewRecord`
359
+ и evidence пределов не получили.
360
+
327
361
  ## Выходы
328
362
 
329
363
  ### RunResult
@@ -704,29 +738,31 @@ stdout — один JSON `CliEnvelope`: `{apiVersion, command, ok: true, data}`
704
738
  читающие на отсутствующем каталоге отвечают `NOT_FOUND` и ничего не создают.
705
739
  Бинарник не хранит настроек проекта и не помнит «последний активный проект».
706
740
 
707
- | Команда | Аргументы | Пишет | `data` | Повтор |
708
- | ----------------- | -------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
709
- | `validate` | `--graph F --policy F [--context F]` | нет | digests, число поручений | Чистая функция входов |
710
- | `review-plan` | `--state D --graph F --policy F --author A [--context F]` | да | `ReviewRecord` | Тот же digest и автор, уже согласованные, — тот же раунд без вызова модели; автор, не допускаемый правилом вендора, — `REVIEWER_SAME_VENDOR` до вызова |
711
- | `review-contract` | `--state D --contract F --policy F --author A` | да | `ReviewRecord` | Как `review-plan` |
712
- | `approve` | `--state D --subject ID --digest H` | да | subject, digest, at | Тот же digest — без изменений; только `approvalMode: operator` |
713
- | `run` | `--state D --graph F --policy F [--context F] [--sink file:D] [--once]` | да | граф, поручения и их блокеры, задание `workflow` | Та же редакция продолжает работу; другой digest той же редакции — `REVISION_CONFLICT` |
714
- | `status` | `--state D [--graph ID]` | нет | очередь, графы, поручения с блокерами, бюджеты | Только чтение |
715
- | `events` | `--state D [--after N] [--limit 1–500]` | нет | события, `next` | Только чтение |
716
- | `pause` | `--state D` | да | `ControlState` | Без изменений |
717
- | `resume` | `--state D` | да | `ControlState` | Решение человека: снимает паузу оператора, штатной остановки и отказа runtime вместе с её классами; паузу операции reconfigure — `PAUSED` |
718
- | `cancel` | `--state D --work ID [--reason T]` | да | статус поручения | Отменённое — без изменений; это не retry |
719
- | `retry` | `--state D --work ID [--reset --reason T]` | да | статус поручения | В пределах `maxAttempts` и бюджета; `--reset` с причиной сбрасывает счётчик попыток, но не учёт расходов |
720
- | `result` | `--state D --work ID` | нет | `ResultEnvelope` | Только чтение |
721
- | `deliver` | `--state D --work ID --sink file:D` | да | `ResultEnvelope` | Доставленное не доставляется повторно; моделей и интеграции нет |
722
- | `profile` | `--profile ID\|./F [--repository D]` | нет | закрепление (`pin`) и разрешённый профиль | Чистая функция файлов профиля; команды проекта не исполняются |
723
- | `doctor` | `[--state D] [--policy F]` | нет | версии, runtime, sandbox, совместимость состояния и версии движка в нём | Без live-вызова модели |
724
- | `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
725
- | `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
726
- | `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
727
- | `plan-check` | `--draft F --policy F [--context F] [--contracts D] [--brief F [--basis H]]` | нет | `issues`, `checkPlan`; без проблем — `graph`, `graphDigest`, `basis` | Чистая функция входов и `HEAD` источников требований; согласования не выдаёт, gates не запускает; расхождение `--basis` — `APPROVAL_STALE` |
728
- | `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
729
- | `--version` | — | нет | версия пакета и API | — |
741
+ | Команда | Аргументы | Пишет | `data` | Повтор |
742
+ | ------------------ | -------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
743
+ | `validate` | `--graph F --policy F [--context F]` | нет | digests, число поручений | Чистая функция входов |
744
+ | `review-plan` | `--state D --graph F --policy F --author A [--context F]` | да | `ReviewRecord` | Тот же digest и автор, уже согласованные, — тот же раунд без вызова модели; автор, не допускаемый правилом вендора, — `REVIEWER_SAME_VENDOR` до вызова |
745
+ | `review-contract` | `--state D --contract F --policy F --author A` | да | `ReviewRecord` | Как `review-plan` |
746
+ | `approve` | `--state D --subject ID --digest H` | да | subject, digest, at | Тот же digest — без изменений; только `approvalMode: operator` |
747
+ | `run` | `--state D --graph F --policy F [--context F] [--sink file:D] [--once]` | да | граф, поручения и их блокеры, задание `workflow` | Та же редакция продолжает работу; другой digest той же редакции — `REVISION_CONFLICT` |
748
+ | `status` | `--state D [--graph ID]` | нет | очередь, графы, поручения с блокерами, бюджеты | Только чтение |
749
+ | `events` | `--state D [--after N] [--limit 1–500]` | нет | события, `next` | Только чтение |
750
+ | `pause` | `--state D` | да | `ControlState` | Без изменений |
751
+ | `resume` | `--state D` | да | `ControlState` | Решение человека: снимает паузу оператора, штатной остановки и отказа runtime вместе с её классами; паузу операции reconfigure — `PAUSED` |
752
+ | `cancel` | `--state D --work ID [--reason T]` | да | статус поручения | Отменённое — без изменений; это не retry |
753
+ | `retry` | `--state D --work ID [--reset --reason T]` | да | статус поручения | В пределах `maxAttempts` и бюджета; `--reset` с причиной сбрасывает счётчик попыток, но не учёт расходов |
754
+ | `result` | `--state D --work ID` | нет | `ResultEnvelope` | Только чтение |
755
+ | `deliver` | `--state D --work ID --sink file:D` | да | `ResultEnvelope` | Доставленное не доставляется повторно; моделей и интеграции нет |
756
+ | `cleanup` | `--state D --run ID` | да | исход очистки попытки |
757
+ | `worktree-cleanup` | `--state D [--dry-run]` | да | счётчики и `worktrees[]` с действием и причиной отказа |
758
+ | `profile` | `--profile ID\|./F [--repository D]` | нет | закрепление (`pin`) и разрешённый профиль | Чистая функция файлов профиля; команды проекта не исполняются |
759
+ | `doctor` | `[--state D] [--policy F]` | нет | версии, runtime, sandbox, совместимость состояния и версии движка в нём | Без live-вызова модели |
760
+ | `init` | `--repository D [--profile P] [--writer R] [--state D] [--plan]` | да | план файлов, `created`, `manifest`, `facts`, `toolchain`, `next` | Create-only `.harness/`, manifest до политики, политика последней; повтор — `created: []`; иное решение — `PATH_CONFLICT` |
761
+ | `explain` | `--state D --policy F [--work ID]` | нет | `diagnoses[]` (`StopDiagnosis`) | Только чтение: без повторов, вызовов моделей и изменений состояния |
762
+ | `plan-request` | `--brief F --policy F [--context F] [--contracts D] [--requirements [R:]F]… [--human]` | нет | `prompt`, `readOnly`, `recommendedTasks`, `maxTasks`, `basis`, `facts` (`PlanningFacts`) | Чистая функция входов: та же постановка и те же факты — тот же prompt и `basis`; модель не вызывается |
763
+ | `plan-check` | `--draft F --policy F [--context F] [--contracts D] [--brief F [--basis H]]` | нет | `issues`, `checkPlan`; без проблем — `graph`, `graphDigest`, `basis` | Чистая функция входов и `HEAD` источников требований; согласования не выдаёт, gates не запускает; расхождение `--basis` — `APPROVAL_STALE` |
764
+ | `capabilities` | — | нет | каталог общих операций (`OperationCatalog`) | Чистая функция установленной версии пакета |
765
+ | `--version` | — | нет | версия пакета и API | — |
730
766
 
731
767
  Полная форма каждой команды — `cliCommands` (аргументы, обязательность,
732
768
  идемпотентность, отказы exit 3). Все команды реализованы. `run` принимает `--author` (по умолчанию `external`) — автора графа для ревью плана. `HARNESS_CODEX_BIN` и `HARNESS_CLAUDE_BIN` подменяют исполняемые файлы runtime (fixture executables в тестах).
@@ -0,0 +1,35 @@
1
+ # devcontour-harness 0.1.0-alpha.26
2
+
3
+ Базовая линия коннектора для существующих проектов, исправление снимка с
4
+ пакетами контекста, причина отказа gate в итоге проверки, обновление
5
+ зависимостей и пределы недоверенного вывода runtime. Обязательные gates,
6
+ fencing и привязка доказательств к SHA не меняются.
7
+
8
+ ## Изменения
9
+
10
+ - **Базовая линия коннектора.** Поле `baseline` конфигурации (`sha`, `tasks`,
11
+ `reason`) допускает завершённую зависимость, закрытую вне harness, если она
12
+ названа по ключу, а SHA достижим в target ref. Настоящий receipt важнее.
13
+ В снимке такая зависимость отмечена `proof: baseline`: это решение человека,
14
+ а не доказательство. С `baseline` конфигурация обязана лежать вне
15
+ репозиториев политики или в `protectedPaths`.
16
+ - **`source-snapshot` с пакетами контекста.** CLI больше не падает с INTERNAL
17
+ на поле `localContext`. Пакет вне договора источника и недопустимый
18
+ `writeScope` отказывают раньше и с именем поля. Нарушение договора вывода
19
+ показывает пути полей.
20
+ - **Причина отказа gate.** Первая ошибка компилятора с координатами
21
+ дописывается перед прежним хвостом вывода: хвост не меняется, поэтому
22
+ отпечаток отказа не теряет различий. Окно отпечатка расширено до 4000
23
+ символов; некоторые длинные отказы получат новый отпечаток.
24
+ - **Зависимости.** zod 4.6.7, node-forge 1.4.2, fast-uri 3.1.9. Транзитивный
25
+ zod 3.25.76 в sandbox-runtime остаётся: исправленного выпуска 3.x нет.
26
+ - **Пределы вывода runtime.** `findings` и `previous` — до 500, Codex
27
+ `result.json` — до 4 МиБ с ограниченным чтением, файл результата проверки —
28
+ до 1 МиБ, массивы ответов Relay — до 10 000. Сверх предела — обычный отказ
29
+ попытки с причиной. Сохранённые записи читаются без этих пределов.
30
+
31
+ ## Обновление
32
+
33
+ Пакет alpha.25 остаётся неизменным. Перед обновлением остановите writers и
34
+ сохраните копию состояния. Преобразование состояния не требуется. Хостам с
35
+ собственным zod нужна та же версия 4.6.7, чтобы осталась одна копия.
@@ -0,0 +1,36 @@
1
+ # devcontour-harness 0.1.0-alpha.27
2
+
3
+ Хранилище зависимостей pnpm, объявляемое в политике, команда уборки рабочих
4
+ деревьев завершённых попыток, более дешёвый поиск оставшихся процессов и
5
+ отказ до заведомо безуспешного вызова ревьюера. Обязательные gates, fencing и
6
+ привязка доказательств к SHA не меняются.
7
+
8
+ ## Изменения
9
+
10
+ - **Хранилище зависимостей.** Необязательное поле
11
+ `repositories[].dependencyStore` (`manager: 'pnpm'`, `lockfile`, `maxBytes`,
12
+ `timeoutMs`). Seed собирается только из lockfile целевого ref и копируется
13
+ в `<checkout>/.pnpm-store`. Исход пишется в `dependency-store.json`: `hit`,
14
+ `partial` или `miss`. Отказ хранилища не стоит попытки: установка идёт
15
+ обычным путём. Поддержан pnpm `>=9.15.0 <10.27.0`; границы описаны в
16
+ `docs/compatibility.md`. Linux не проверялся.
17
+ - **`harness worktree-cleanup --state S [--dry-run]`.** Удаляет
18
+ зарегистрированные деревья завершённых попыток; ветки, объекты и артефакты
19
+ остаются. Незакоммиченные правки сначала сохраняются в patch. Дерево, которое
20
+ нельзя доказуемо восстановить, не удаляется, а отказ назван. Деревья с Git
21
+ LFS отказываются намеренно.
22
+ - **Поиск потомков.** Проверяются только процессы моложе команды: около 26 мс
23
+ вместо 341 мс на команду.
24
+ - **Ревью.** Проверка плана и договора останавливается до вызова, который не
25
+ может завершиться успешно. Открытые находки считаются по ID перед пределом
26
+ раунда.
27
+ - **Коннектор.** Понятный отказ, если конфигурация с baseline исчезла после
28
+ загрузки; `source-snapshot` снова закрепляет более раннюю ревизию.
29
+ - **Тесты.** У каждого прогона свой временный каталог, который удаляется в
30
+ конце; чувствительные к нагрузке тесты ждут событий, а не таймеров.
31
+
32
+ ## Обновление
33
+
34
+ Пакет alpha.26 остаётся неизменным. Перед обновлением остановите writers и
35
+ сохраните копию состояния. Преобразование состояния не требуется. Без поля
36
+ `dependencyStore` поведение установки не меняется.
@@ -74,6 +74,14 @@ ID: дедупликации по тексту нет, поэтому повто
74
74
 
75
75
  `note`, оставленная открытой явным переходом, не мешает `approved: true`.
76
76
 
77
+ **Пределы.** В ответе не больше 500 находок и 500 переходов
78
+ (`REVIEW_ITEMS_LIMIT`): больше — ошибка `schema` с путём `findings` или
79
+ `previous`. Файл ответа codex больше предела в ревью кода — ошибка `schema` с
80
+ путём `(response)`, как и нечитаемый ответ; в ревью плана и контракта это
81
+ отказ `RUNTIME_UNAVAILABLE` (§8). Если открытых находок поручения больше 500,
82
+ раунд не записать: попытка останавливается с `review-protocol` до вызова
83
+ reviewer.
84
+
77
85
  **Атомарность.** Ответ проверяется целиком до любой записи. Невалидный ответ
78
86
  не закрывает ни одной находки, не создаёт новых и не даёт PASS: он
79
87
  сохраняется только как диагностика (сырой ответ — в своём `review.json`,
@@ -208,9 +216,15 @@ id = digestOf({ v: 'legacy-1', scope, evidence: e.id, runId, phase, sha, index,
208
216
  `technicalReview` (ревью плана и контракта) применяет то же правило
209
217
  атомарности: невалидный ответ (вне схемы или с нарушением `reviewIssues`)
210
218
  не применяет переходы и не добавляет находок; раунд записывается
211
- неодобренным с причинами. Повторно найденная закрытая находка с тем же ID
219
+ неодобренным с причинами (у ответа вне схемы — путь поля и сообщение первой
220
+ ошибки). Повторно найденная закрытая находка с тем же ID
212
221
  открывается снова, а не отбрасывается как дубликат. Формат `ReviewRecord`
213
- не меняется.
222
+ не меняется. Если открытых находок предмета больше 500
223
+ (`REVIEW_ITEMS_LIMIT`), ответ не смог бы назвать их все: раунд
224
+ останавливается отказом `REVIEW_PROTOCOL_INVALID` до вызова reviewer.
225
+ Ответ, который адаптер не смог прочитать (в том числе файл ответа codex
226
+ больше предела), не становится раундом: это отказ `RUNTIME_UNAVAILABLE` с
227
+ причиной, без записи в историю.
214
228
 
215
229
  ## 9. Адаптеры без протокола переходов (совместимость хостов)
216
230