| 1 | # Playbook: agent execution environment v1 |
| 2 | |
| 3 | ADR: [0148](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md) |
| 4 | Naming: [naming-layers-v1.md](naming-layers-v1.md) · UX: [agent-verify-epoch-view-v1.md](agent-verify-epoch-view-v1.md) |
| 5 | KB (agent-notes MCP): `knowledge/work/projects/door-to-singularity/cascade-ide/playbook-agent-execution-environment-v1.md` в каноне (`AGENT_NOTES_CANON_PATH`, типично `D:\Experiments\agent-notes`). |
| 6 | Связь: [0141](../adr/0141-solution-scoped-warmup-orchestration.md) (warm substrate), [0038](../adr/0038-agent-facade-ai-provider-and-tool-orchestration.md) (фасад), [0138](../adr/0138-cockpit-command-line-and-parametric-ranges.md) (CCL/slash). |
| 7 | |
| 8 | Полная норма: ADR [0148 §2.2–2.3, §5.1](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md). |
| 9 | |
| 10 | ## Культура сессии |
| 11 | |
| 12 | *Читай ADR → спорь с нормой → дописывай историю.* — не «лычка senior» в промпте, а работа с **памятью команды** (ADR, playbook, rejected, history). Развёрнуто: [cascadeide-philosophy-v1 §8.1](../design/cascadeide-philosophy-v1.md#81-память-команды-не-лычка-в-промпте). |
| 13 | |
| 14 | ## Тезис: два такта |
| 15 | |
| 16 | | Такт | Что ограничивает | Типичный dev tooling | |
| 17 | |------|------------------|----------------------| |
| 18 | | **Когнитивный** | Скорость мышления (человек, агент ×10–×100) | Не учитывается | |
| 19 | | **Среды** | Build, test, shell, I/O, DB lock, cold start | **Единственный**, на котором всё «висит» | |
| 20 | |
| 21 | Проблема не в том, что «агент медленный», а в том, что **среда не успевает за мыслью**. Cursor/MCP/shell-first цикл усиливает это: каждый шаг — round-trip + subprocess + ожидание человека на verify. |
| 22 | |
| 23 | CascadeIDE standalone должна **сопоставить bandwidth среды с bandwidth мышления**: параллельный verify, push вместо poll, in-process Roslyn/build/test, прозрачный учёт времени. |
| 24 | |
| 25 | ## Открытый .NET stack (кратко) |
| 26 | |
| 27 | CLI (`dotnet build|test|format`) — оболочка над **MIT/Apache** библиотеками. AEE **не форкает SDK**; `diagnose.files` Roslyn in-proc; `compile.project`+ — **supervised build host** ([0148 §5.2](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md)). Subprocess — E-tier. |
| 28 | |
| 29 | | verify_rung | MLP | |
| 30 | |-------------|-----| |
| 31 | | `diagnose.files` | Roslyn diagnostics + format (in-proc; SG-aware) | |
| 32 | | `compile.project` | Semantic compile affected projects (build host) | |
| 33 | | `build.affected` | Incremental project build (build host) | |
| 34 | | `test.scoped` | Supervised test host, filter | |
| 35 | | `test.full` | Full suite (ideal / ci_parity) | |
| 36 | |
| 37 | Детали, границы (VS IDE, Code Coverage license, VMR): [0148 §2.3](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md). |
| 38 | |
| 39 | ## Verification ladder (кратко) |
| 40 | |
| 41 | | verify_rung | Действие | Цель | |
| 42 | |-------------|----------|------| |
| 43 | | **`diagnose.files`** | Roslyn diagnostics по затронутым файлам | Секунды, без shell | |
| 44 | | **`compile.project`** | Compile / semantic model affected projects | Cross-file types без full build | |
| 45 | | **`build.affected`** | Incremental build project(s) | NuGet/refs, MSBuild graph | |
| 46 | | **`test.scoped`** | Filtered tests | Поведение, unit scope | |
| 47 | | **`test.full`** | Full suite / integration | Merge gate, ci_parity | |
| 48 | |
| 49 | Legacy `L0–L4` — **не использовать** в UI и новых docs ([naming-layers-v1.md](naming-layers-v1.md)). |
| 50 | |
| 51 | Политики: `minimal` | `standard` (default) | `strict` | `ci_parity`. Агент **не блокирует чат** на `build.affected`+ — runner + DataBus + Verify Epoch UI ([agent-verify-epoch-view-v1.md](agent-verify-epoch-view-v1.md)). |
| 52 | |
| 53 | ## W1 (первая поставка кода) |
| 54 | |
| 55 | 1. **`EnvironmentTaskRunner`** — очередь, cancel, progress, id; **одна** verify-цепочка; implicit cancel predecessor. |
| 56 | 2. **`verify_snapshot_id`** + stale на write в `in_verification` set (DataBus `AgentVerifyEpochStale`). |
| 57 | 3. **События в DataBus** — `environment.task.*` + `AgentEnvironmentTaskDied` ([0099](../adr/0099-databus-event-fabric-and-cross-feature-notifications.md)). |
| 58 | 4. **Time accounting в чате** — wall / active / environment / **blocked** (не `idle_user` — W3+). |
| 59 | 5. **Slash** — `/agent verify`, `/agent cancel`, `/agent status` ([0138](../adr/0138-cockpit-command-line-and-parametric-ranges.md)). |
| 60 | 6. **Ephemeral sandbox** — substrate bundle (WitDB + ports + temp); fresh per `test.scoped`+ task. |
| 61 | |
| 62 | На rung `test.scoped` переменные **`CASCADE_AGENT_SUBSTRATE_WIT_DB`** и **`CASCADE_AGENT_SUBSTRATE_DEV_PORT`** добавляются в среду процесса `dotnet test`. |
| 63 | |
| 64 | Не в W1: worktree sandbox, batch native tools, PFD Verify Epoch instrument, gutter dim для epoch, `idle_user`. |
| 65 | |
| 66 | ## Матрица согласованности среды (W1–MLP) |
| 67 | |
| 68 | Сводка для runner / UI / orchestrator — норма [0148 §8](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md): |
| 69 | |
| 70 | | Зона | MLP | Не в MLP | |
| 71 | |------|-----|----------| |
| 72 | | Stale context | `verify_snapshot_id` + coalesce 1.5 s; green **S** ≠ **S′** | Auto-rollback tree; worktree на каждый verify | |
| 73 | | State bleeding | Fresh **substrate bundle** per `test.scoped`+ task | Rollback-only в тестах | |
| 74 | | Metrics | reasoning \| environment \| blocked | `idle_user` (W3+) | |
| 75 | | Source generators | SG-aware `diagnose.files` → `compile.project` host | Отдельный GeneratorDriver в CIDE | |
| 76 | |
| 77 | ## Слепые зоны (концептуальный аудит, review Orion 2026-05-25) |
| 78 | |
| 79 | Четыре темы, которые легко недооценить при W2–W4. Нормативная деталь — [0148 §8.1](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md). |
| 80 | |
| 81 | ### 1. Stale context (параллельный когнитивный и средовой такт) |
| 82 | |
| 83 | Пока runner гоняет `build.affected`/`test.scoped`, агент/оператор может **писать дальше**. Падение verify через 40 с не откатывает «мысль за эти 40 с» автоматически. |
| 84 | |
| 85 | | Подход | MLP | Идеал | |
| 86 | |--------|-----|-------| |
| 87 | | **Verify epoch** — каждый run привязан к `snapshot_id` (git HEAD + dirty set) | ✓ в метаданных run | UI Verify Epoch ([agent-verify-epoch-view-v1.md](agent-verify-epoch-view-v1.md)) | |
| 88 | | **Implicit cancel predecessor** — новый verify отменяет старый на `compile.project`+ | ✓ W1 | | |
| 89 | | **Soft lock** — предупреждение при правке файлов из `in_verification` set | ✓ stale event; gutter dim W3+ | | |
| 90 | | **Environment branch** — когнитивный такт агента в `agent_worktree` до green | W4/W6 | default для autonomous long runs | |
| 91 | | Hard rollback operator workspace к pre-verify | ✗ default | опасно сотрёт работу человека | |
| 92 | |
| 93 | **Не путать** с sandbox DB: это про **согласованность кода и гипотезы «билд зелёный»**. |
| 94 | |
| 95 | ### 2. Идемпотентность ephemeral DB (state bleeding) |
| 96 | |
| 97 | `test.scoped`/`test.full` **пишут** в БД. Повторный прогон на той же temp DB — грязное состояние. |
| 98 | |
| 99 | | Подход | Когда | |
| 100 | |--------|-------| |
| 101 | | **Fresh substrate per ladder jump** — новый **bundle** (data dir + ports + temp) перед каждым `test.scoped`+ task | MLP для integration | |
| 102 | | **CoW / snapshot** data dir (SQLite file copy, volume snapshot) | ideal | |
| 103 | | **Rollback transaction** на test host после run | если тесты поддерживают shared fixture — осторожно | |
| 104 | |
| 105 | Связь с §6 ADR: ephemeral ≠ «одна БД на всю сессию агента». |
| 106 | |
| 107 | ### 3. Metrics dilution (blocked vs idle human) |
| 108 | |
| 109 | `Blocked Time` = ожидание **среды**. Если оператор ушёл за кофе — это не fault tooling. |
| 110 | |
| 111 | | Фаза | Смысл | |
| 112 | |------|-------| |
| 113 | | `reasoning` | Модель / orchestrator | |
| 114 | | `environment` | Runner / build host | |
| 115 | | `idle_user` | Нет фокуса CIDE / нет ввода N сек (опционально W3+) | |
| 116 | | `blocked` | Только когда run **активен** и среда не отвечает | |
| 117 | |
| 118 | Иначе аналитика «эффективности агента» смешивает Slack и MSBuild. |
| 119 | |
| 120 | ### 4. Roslyn `diagnose.files` vs Source Generators |
| 121 | |
| 122 | Diagnostics **без** сгенерированных документов даёт ложные CS1061 при зелёном `dotnet build` (см. roslyn-mcp / [0058](0058-agent-roslyn-mcp-coupling-settings-toml.md)). |
| 123 | |
| 124 | | Подход | Владелец | |
| 125 | |--------|----------| |
| 126 | | `GetSourceGeneratedDocumentsAsync` + актуальный `CurrentSolution` | `diagnose.files` path (Roslyn in-proc) | |
| 127 | | Warm item `agent.source_generators` / reuse 0141 HCI sidecar | [0141](../adr/0141-solution-scoped-warmup-orchestration.md) P2+ | |
| 128 | | Если SG не прогрет — **не обещать** мгновенный `diagnose.files`; поднимать rung до `compile.project` | ladder policy | |
| 129 | |
| 130 | **Правило:** `diagnose.files` green **не** auto-climb на `compile.project`, если SG stale. |
| 131 | |
| 132 | ## Операционные инварианты (Orion round 2, 2026-05-25) |
| 133 | |
| 134 | Норма: [0148 §8.1.1, §8.1.5](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md). |
| 135 | |
| 136 | ### Verify coalesce + cancel |
| 137 | |
| 138 | - После окна coalesce новый verify **отменяет** предыдущий на `compile.project`+ (implicit cancel predecessor). |
| 139 | - Две параллельные verify-цепочки в одной session — **запрещены**. |
| 140 | |
| 141 | ### Human parity (оператор в контуре) |
| 142 | |
| 143 | - Те же stale rules, что для агента: write в файл epoch → `AgentVerifyEpochStale` сразу. |
| 144 | - W3+: Verify Epoch UI + gutter dim ([agent-verify-epoch-view-v1.md](agent-verify-epoch-view-v1.md)). |
| 145 | |
| 146 | ### Supervised host death |
| 147 | |
| 148 | - Crash/OOM host → `AgentEnvironmentTaskDied`, не ждать timeout. |
| 149 | - Orchestrator: alert + restart host; не assume green. |
| 150 | |
| 151 | ## Для быстрого оператора (человек) |
| 152 | |
| 153 | - Те же runner и ladder — не «только для агента». |
| 154 | - Keyboard/slash первичны; mouse — для обзора, не для unblock. |
| 155 | - Warm-up ([0141](../adr/0141-solution-scoped-warmup-orchestration.md)) снижает latency `compile.project` до открытия solution. |
| 156 | |
| 157 | ## Анти-паттерны |
| 158 | |
| 159 | - Default `dotnet test` без filter после каждой правки. |
| 160 | - Shell как единственный verify path для C#. |
| 161 | - Блокирующий чат до зелёного CI локально. |
| 162 | - Скрытое время среды (агент «думает», пока идёт build). |
| 163 | - «Агент сказал green» без Verify Epoch на **текущем** snapshot (Cursor anti-pattern). |
| 164 | - Писать код «как будто verify уже зелёный», не глядя на verify epoch / stale run. |
| 165 | - Переиспользовать одну ephemeral БД на несколько `test.scoped`+ без refresh substrate. |
| 166 | - Две параллельные `/agent verify` без отмены первой. |
| 167 | - Считать green завершённого verify после правки файлов из epoch dirty set. |
| 168 | - Голые «L2» в verify-контексте — использовать `verify_rung` ([naming-layers-v1.md](naming-layers-v1.md)). |
| 169 | |
| 170 | ## Локальный test-drive (Orion) |
| 171 | |
| 172 | - Док: [aee-orion-local-test-drive-v1.md](aee-orion-local-test-drive-v1.md) |
| 173 | - Скрипт: `scripts/aee/orion-test-drive.ps1` |
| 174 | - xUnit: `Category=AgentEnvironment` → `AgentEnvironmentOrionStressTests` |
| 175 | |
| 176 | ## Открытые вопросы (из ADR) |
| 177 | |
| 178 | Orchestrator ownership, ACP parity, auto test filters, CASCOPE для raw shell, cross-platform process supervise — см. [0148 § Open questions](../adr/0148-agent-execution-environment-verification-ladder-and-native-tooling.md). |
| 179 | |