m/Assistant
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
939a5152e1f417eff21f5c64dacca4cd8689638d
Assistant/development/GEN2_EXECUTION_CONTRACT.md
T
m 939a5152e1
CI / test (push) Successful in 48s
Details
ARCH-GEN2-000: adopt Gen2 architecture governance
2026-08-29 01:53:27 +03:00

15 KiB
Raw Blame History

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

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 может строиться на результате без архитектурного долга, который мы сознательно откладываем.
Reference in New Issue View Git Blame Copy Permalink