Assistant/development/GEN2_EXECUTION_CONTRACT.md

# DOMOVOY Gen2 — Execution Contract for Codex

## 1. Назначение

Этот документ определяет, **как выполнять** `PRE-GEN2-000`, `ARCH-GEN2-000` и `GEN2-001…GEN2-030`.

Он не заменяет:
- `DOMOVOY_CONSTITUTION.md`;
- `GEN2_TARGET_ARCHITECTURE.md`;
- `GEN2_CANONICAL_DATA_MODEL.md`;
- `GEN2_MIGRATION_MAP.md`;
- `GEN2_MASTER_PLAN.md`.

При конфликте действуют существующий `AGENTS.md` и canonical architecture authority order. Если конфликт нельзя снять однозначно — `BLOCKED_BY_SPEC_GAP` / `BLOCKED_BY_ARCHITECTURE_GAP`, а не обход.

## 2. Почему `ARCH-GEN2-000`, а не `GEN2-000`

Текущий `devctl` принимает `architecture_revision` только как:
- принятый `ADR-*`; или
- существующий architecture task с префиксом `ARCH-*`.

Поэтому Master Plan task `GEN2-000 — Adopt Gen2 ...` исполняется как:

`ARCH-GEN2-000`

Смысл задачи не изменён. Все последующие `GEN2-*` используют:

`"architecture_revision": "ARCH-GEN2-000"`

## 3. Нулевой принцип

**Цель — построить Gen2, а не бесконечно проверять тесты.**

Тесты дают достаточное доказательство сохранения критических свойств. Они не являются самостоятельным продуктом.

Не добавлять тест только потому, что можно добавить ещё один edge case.

## 4. PRE-GEN2: сначала сохранить всё текущее

До любых Gen2 semantic/schema изменений выполнить `PRE-GEN2-000`.

### 4.1 Инвентаризация

Проверить:
- `git status`;
- все worktrees;
- все локальные ветки;
- ветки, опережающие `main`;
- staged / unstaged / untracked files;
- незапушенные commits;
- merge/rebase/cherry-pick state.

Ничего не удалять и не делать `reset --hard` до классификации каждого изменения.

### 4.2 Preservation

Для каждого актуального открытого изменения:
1. понять происхождение;
2. исключить secrets/generated/runtime garbage;
3. сохранить актуальную работу commit-ом;
4. не переписывать опубликованную историю;
5. не терять конфликтующую ветку ради удобного merge.

### 4.3 Merge

После preservation:
1. обновить локальный `main`;
2. контролируемо слить всю актуальную работу;
3. разрешить конфликты по смыслу, сохраняя существующее поведение;
4. выполнить только PRE FAST gate;
5. push `main`.

### 4.4 Baseline

После успешного push:
- записать SHA как `GEN2_BASE_COMMIT`;
- поставить baseline tag `domovoy-pre-gen2`;
- сохранить baseline report;
- создать ветку `gen2-integration` от baseline;
- push `gen2-integration`.

Если tag уже существует, не перезаписывать его молча: использовать duplicate-safe имя с датой/коротким SHA и записать фактическое имя в report.

## 5. Как установить execution package

До `PRE-GEN2-000` в репозиторий копируются **только**:
- `bootstrap/dev/tasks/PRE-GEN2-000-*.json` -> `dev/tasks/`;
- `bootstrap/dev/ACTIVE_TASK.json` -> `dev/ACTIVE_TASK.json`.

Остальные Gen2 документы/task packets не должны случайно попасть в V1 baseline как «реализация Gen2».

После PRE baseline:
1. checkout `gen2-integration`;
2. создать branch для `ARCH-GEN2-000`;
3. скопировать содержимое `program/docs/gen2/` в согласованные canonical repo paths;
4. скопировать `program/dev/tasks/*.json` в `dev/tasks/`;
5. заменить `dev/ACTIVE_TASK.json` содержимым `program/dev/ACTIVE_TASK.arch-gen2-000.json`;
6. выполнить `ARCH-GEN2-000`.

## 6. Branch model

После PRE каждая задача выполняется отдельно.

### 6.1 Перед task

```text
checkout gen2-integration
pull/verify expected head
create branch gen2/<task-id>-<short-slug>
set dev/ACTIVE_TASK.json -> selected packet
run preflight
```

Все post-PRE task packets имеют:

`"base_repo_revision": "gen2-integration"`

Это намеренно.

Пока Codex работает в task branch, локальная ветка `gen2-integration` остаётся на исходной точке задачи. Поэтому `check-diff` видит **только diff текущего packet-а**, а не всю программу Gen2.

### 6.2 После FAST gate

1. `check-diff`;
2. `git diff --check`;
3. commit task branch;
4. merge task branch -> `gen2-integration`;
5. push `gen2-integration`;
6. удалить task branch только после проверки merge.

Не сливать незавершённый packet в integration ради «сохранения прогресса»: для этого используются commits в task branch.

## 7. Milestone merge в main

`main` обновляется по реперным точкам, а не после каждой мелкой задачи.

Milestone exit:
1. выполнить соответствующий `MILESTONE` или `FULL` gate на `gen2-integration`;
2. только если gate зелёный — merge `gen2-integration` -> `main`;
3. push `main`;
4. поставить milestone tag;
5. fast-forward `gen2-integration` до нового `main` merge commit;
6. push `gen2-integration`.

Рекомендуемые tags:
- `domovoy-gen2-m0`
- `domovoy-gen2-m1`
- …
- `domovoy-gen2-m6`

Не перезаписывать существующий tag.

## 8. Test profiles

### 8.1 FAST — основной цикл

FAST выполняется на каждом task.

Состав:
- targeted `go test` только изменённого owner/runtime;
- targeted `go vet`;
- `devctl preflight`;
- `devctl check-diff`;
- `devctl/independent`;
- `git diff --check`;
- один-два regression checks для фактического риска task-а.

**FAST не включает `go test ./...` по умолчанию.**

Если targeted command невозможно корректно сформировать из-за package topology, сначала объяснить почему; не переходить автоматически на полный suite без причины.

### 8.2 MILESTONE

MILESTONE запускается после завершения целого архитектурного органа.

Только:
- затронутые owners;
- соседние contracts;
- migration/backfill sample;
- ключевые cross-owner regressions;
- restart/recovery там, где это часть milestone.

### 8.3 FULL

FULL запускается только там, где packet прямо содержит `FULL:` evidence.

Базовые FULL points:
- `GEN2-016` — M3;
- `GEN2-027` — M5;
- `GEN2-029` — до необратимого V1 retirement;
- `GEN2-030` — финальный acceptance.

Дополнительный FULL допустим только при:
- критической глобальной schema migration;
- изменении Authority/Commit invariants;
- серьёзном production rollback concern;
- явном требовании владельца.

### 8.4 Не повторять свежий FULL без причины

Если предыдущий FULL:
- выполнен на том же milestone;
- после него не менялась соответствующая глобальная поверхность;
- нет нового риска, который он должен покрыть,

не запускать его повторно «для уверенности».

## 9. STOP TEST EXPANSION

Codex обязан остановить расширение тестов и вернуться к цели task-а, если одновременно верно:

1. функциональная/архитектурная цель ещё не достигнута;
2. тестовая работа стала существенно больше самой реализации;
3. новые тесты проверяют уже защищённый invariant или косметические вариации;
4. нет нового существенного риска, ради которого они нужны.

В этом случае:
- оставить минимально достаточные tests;
- записать потенциальные дополнительные cases в findings;
- продолжить реализацию.

## 10. Architecture and migration law

### 10.1 Один canonical writer

Никогда не иметь два canonical writers одного mutable semantic state.

Разрешено:
- backfill;
- shadow projection;
- dual-read;
- compare;
- read fallback.

Не разрешено:
- два равноправных canonical write paths «на время миграции».

### 10.2 Historical migrations

Не редактировать V1 migrations `001–045`.

Gen2 создаёт только новые next-numbered migrations.

Если порядковый номер изменился из-за параллельной работы, использовать следующий свободный — смысл migration определяется task, а не заранее зарезервированным числом.

### 10.3 Особенность текущего devctl

Текущий validator трактует **любое** изменение `database/**` как требующее положительного `new_database_owner_roles`, а любое изменение `deploy/**` — положительного `new_privileges`.

Поэтому packets на этих поверхностях содержат `1` как compatibility gate.

Это **не означает**, что task автоматически разрешает:
- новый semantic owner;
- новый DB role;
- cross-owner FK/JOIN/write;
- дополнительную внешнюю привилегию.

Разрешено только то, что явно написано в packet + Gen2 architecture docs.

`ARCH-GEN2-000` может улучшить этот validator, но должен сохранить обратную совместимость с уже созданными packets.

## 11. Scope discipline

Task packet — верхняя граница изменения.

Если Codex обнаружил, что нужно изменить файл вне scope:
1. не менять файл;
2. установить, это implementation need или architecture gap;
3. вернуть соответствующий `BLOCKED_*`, либо подготовить revision task packet;
4. после явного расширения scope продолжить.

Не расширять task до соседнего рефакторинга только потому, что он «логично рядом».

## 12. Read before write

Перед нетривиальным изменением:
1. прочитать Gen2 canonical docs;
2. прочитать текущий task packet;
3. найти существующую реализацию/owner;
4. проверить migrations/contracts/call path;
5. только затем менять код.

Если существующий механизм уже решает задачу — расширить его, а не создавать параллельный.

## 13. Data migration rules

Для каждого cutover:
1. additive schema;
2. backfill с lineage;
3. shadow/read comparison;
4. controlled reader switch;
5. writer switch только после доказательства;
6. observation window;
7. V1 compatibility path остаётся до retirement task.

Rollback не должен уничтожать уже накопленные Gen2 evidence.

## 14. Production

Production mutation допускается только packet-ами, где это явно разрешено.

Основной production transition — `GEN2-027`.

Перед promotion:
- health;
- migration compatibility;
- bounded canary;
- household smoke;
- rollback drill.

Если canary неубедителен — rollback считается нормальным результатом, а не провалом программы.

## 15. Self-evolution

До `GEN2-022` SELF/Skill/Reflex не получает права самовольно менять production code.

После `GEN2-022`:
- proposal != promotion;
- creator != evaluator;
- candidate строится отдельно;
- tests/shadow/canary;
- Supervisor держит last-known-good;
- owner intent/authority остаётся выше внутренней оптимизации.

## 16. Completion report каждого task

Codex обязан закончить packet коротким отчётом:

- task id/revision;
- base SHA;
- branch/commit SHA;
- changed paths/modules;
- contracts/schema/events/dependencies/privileges touched;
- writer before/after;
- migration/backfill/cutover state;
- FAST/MILESTONE/FULL tests **фактически** выполненные;
- tests сознательно не выполненные и почему;
- rollback point;
- findings not changed;
- gaps/limitations;
- следующий task, который разрешено активировать.

Не писать `PASS` для теста, который не запускался.

## 17. Terminal states

Допустимые остановки:
- `BLOCKED_BY_SPEC_GAP`
- `BLOCKED_BY_ARCHITECTURE_GAP`
- `BLOCKED_BY_MISSING_CAPABILITY`
- `BLOCKED_BY_CONFLICT`
- `REQUIRES_MIGRATION_DECISION`

Typed stop лучше скрытого архитектурного обхода.

## 18. Главный критерий программы

Успех task-а — не «все возможные тесты зелёные».

Успех:

1. заявленная Gen2 capability/architecture increment реально создана;
2. canonical ownership не размыт;
3. предыдущий критический behavior не сломан;
4. есть достаточное evidence;
5. rollback понятен;
6. следующий packet может строиться на результате без архитектурного долга, который мы сознательно откладываем.