This commit is contained in:
@@ -0,0 +1,367 @@
|
||||
# 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 может строиться на результате без архитектурного долга, который мы сознательно откладываем.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,51 @@
|
||||
# DOMOVOY Gen2 — Task Index
|
||||
|
||||
Это исполняемый индекс task packets. `ARCH-GEN2-000` соответствует разделу `GEN2-000` Master Plan: префикс `ARCH-` нужен текущему `devctl`, чтобы последующие packets могли ссылаться на него через `architecture_revision`.
|
||||
|
||||
| Порядок | Task | Milestone | Gate | Base ref | Зависимость | Файл |
|
||||
|---:|---|---|---|---|---|---|
|
||||
| 1 | `PRE-GEN2-000` | M0 | `FAST` | `origin/main` | — | `PRE-GEN2-000-consolidate-current-development-into-main-and-freeze-baseline.json` |
|
||||
| 2 | `ARCH-GEN2-000` | M0 | `FAST` | `gen2-integration` | PRE-GEN2-000 | `ARCH-GEN2-000-adopt-gen2-constitution-architecture-documents-and-governance-mode.json` |
|
||||
| 3 | `GEN2-001` | M0 | `FAST` | `gen2-integration` | ARCH-GEN2-000 | `GEN2-001-accept-gen2-owner-registry-and-dependency-rules.json` |
|
||||
| 4 | `GEN2-002` | M1 | `FAST` | `gen2-integration` | GEN2-001 | `GEN2-002-introduce-shared-gen2-data-primitives-without-shared-domain-semantics.json` |
|
||||
| 5 | `GEN2-003` | M1 | `FAST` | `gen2-integration` | GEN2-002 | `GEN2-003-add-narrow-world-owner-and-typed-vocabulary.json` |
|
||||
| 6 | `GEN2-004` | M1 | `FAST` | `gen2-integration` | GEN2-003 | `GEN2-004-replace-project-centric-focus-with-contextscope-focusframe-focusstack.json` |
|
||||
| 7 | `GEN2-005` | M1 | `MILESTONE` | `gen2-integration` | GEN2-004 | `GEN2-005-world-identity-resolution-and-version-environment-bindings.json` |
|
||||
| 8 | `GEN2-006` | M2 | `FAST` | `gen2-integration` | GEN2-005 | `GEN2-006-normalize-epistemics-evidence-propositions-claims-and-belief-assessments.json` |
|
||||
| 9 | `GEN2-007` | M2 | `FAST` | `gen2-integration` | GEN2-006 | `GEN2-007-general-freshness-volatility-temporal-applicability-and-revalidation.json` |
|
||||
| 10 | `GEN2-008` | M2 | `FAST` | `gen2-integration` | GEN2-007 | `GEN2-008-promote-episode-and-experience-v2-including-negative-experience.json` |
|
||||
| 11 | `GEN2-009` | M2 | `FAST` | `gen2-integration` | GEN2-008 | `GEN2-009-build-memory-retrieval-fabric-as-rebuildable-projections.json` |
|
||||
| 12 | `GEN2-010` | M2 | `FAST` | `gen2-integration` | GEN2-009 | `GEN2-010-context-compiler-v2-with-budgets-coverage-and-iterative-retrieval.json` |
|
||||
| 13 | `GEN2-011` | M2 | `MILESTONE` | `gen2-integration` | GEN2-010 | `GEN2-011-cut-personalmemory-v1-to-compatibility-fallback.json` |
|
||||
| 14 | `GEN2-012` | M3 | `FAST` | `gen2-integration` | GEN2-011 | `GEN2-012-add-typed-scoped-versioned-configuration-owner-and-bootstrap-boundary.json` |
|
||||
| 15 | `GEN2-013` | M3 | `FAST` | `gen2-integration` | GEN2-012 | `GEN2-013-migrate-skill-v1-to-skill-v2-with-applicability-versioning-and-evidence.json` |
|
||||
| 16 | `GEN2-014` | M3 | `FAST` | `gen2-integration` | GEN2-013 | `GEN2-014-add-explicit-reflex-lifecycle-shadow-reasoning-and-revalidation.json` |
|
||||
| 17 | `GEN2-015` | M3 | `FAST` | `gen2-integration` | GEN2-014 | `GEN2-015-add-evidence-backed-self-foundation-and-learning-ledger.json` |
|
||||
| 18 | `GEN2-016` | M3 | `FULL` | `gen2-integration` | GEN2-015 | `GEN2-016-intelligence-strategy-resource-cost-policy-and-personal-benchmark.json` |
|
||||
| 19 | `GEN2-017` | M4 | `FAST` | `gen2-integration` | GEN2-016 | `GEN2-017-extend-work-into-durable-longrunningwork-investigation.json` |
|
||||
| 20 | `GEN2-018` | M4 | `FAST` | `gen2-integration` | GEN2-017 | `GEN2-018-add-perspective-and-dynamic-specialist-team-semantics-on-existing-work-g.json` |
|
||||
| 21 | `GEN2-019` | M4 | `FAST` | `gen2-integration` | GEN2-018 | `GEN2-019-add-consequence-risk-assessment-without-artificial-capability-blacklist.json` |
|
||||
| 22 | `GEN2-020` | M4 | `FAST` | `gen2-integration` | GEN2-019 | `GEN2-020-separate-execution-receipt-from-verified-world-outcome.json` |
|
||||
| 23 | `GEN2-021` | M4 | `FAST` | `gen2-integration` | GEN2-020 | `GEN2-021-add-independent-supervisor-lifeboat-for-release-health-and-rollback.json` |
|
||||
| 24 | `GEN2-022` | M4 | `MILESTONE_RECOVERY` | `gen2-integration` | GEN2-021 | `GEN2-022-wire-governed-self-evolution-loop-using-existing-development-gates.json` |
|
||||
| 25 | `GEN2-023` | M5 | `FAST` | `gen2-integration` | GEN2-022 | `GEN2-023-make-conversational-control-the-primary-configuration-and-operational-ux.json` |
|
||||
| 26 | `GEN2-024` | M5 | `FAST` | `gen2-integration` | GEN2-023 | `GEN2-024-multi-person-realms-identity-boundaries-and-contextual-source-trust.json` |
|
||||
| 27 | `GEN2-025` | M5 | `FAST` | `gen2-integration` | GEN2-024 | `GEN2-025-multimodal-and-ambient-ingress-readiness-without-implementing-the-whole-.json` |
|
||||
| 28 | `GEN2-026` | M5 | `FAST` | `gen2-integration` | GEN2-025 | `GEN2-026-migrate-household-behavior-to-gen2-context-memory-skills-with-local-degr.json` |
|
||||
| 29 | `GEN2-027` | M5 | `FULL` | `gen2-integration` | GEN2-026 | `GEN2-027-production-canary-and-controlled-gen2-traffic-transition.json` |
|
||||
| 30 | `GEN2-028` | M6 | `FAST` | `gen2-integration` | GEN2-027 | `GEN2-028-inventory-v1-compatibility-usage-and-prove-retirement-readiness.json` |
|
||||
| 31 | `GEN2-029` | M6 | `FULL_RETIREMENT` | `gen2-integration` | GEN2-028 | `GEN2-029-retire-proven-v1-paths-without-deleting-evidence.json` |
|
||||
| 32 | `GEN2-030` | M6 | `FULL_FINAL` | `gen2-integration` | GEN2-029 | `GEN2-030-final-gen2-acceptance-documentation-baseline-and-next-evolution-queue.json` |
|
||||
|
||||
## Реперные точки
|
||||
|
||||
- **M0 exit:** `GEN2-001` — governance/owner registry принят.
|
||||
- **M1 exit:** `GEN2-005` — MILESTONE semantic substrate.
|
||||
- **M2 exit:** `GEN2-011` — MILESTONE memory/context foundation.
|
||||
- **M3 exit:** `GEN2-016` — FULL evolvable behavior.
|
||||
- **M4 exit:** `GEN2-022` — MILESTONE + focused recovery.
|
||||
- **M5 exit:** `GEN2-027` — FULL household/production canary.
|
||||
- **M6 retirement:** `GEN2-029` — FULL before irreversible retirement.
|
||||
- **M6 final:** `GEN2-030` — FULL final acceptance.
|
||||
|
||||
Между реперными точками выполняется только FAST-профиль конкретного packet-а.
|
||||
Reference in New Issue
Block a user