# Домовой — GEN2 Migration Map

Дата: 2026-08-29
Статус: **migration design / input to GEN2 Master Plan**
Основание:
- `DOMOVOY_GEN2_GAP_MAP.md`;
- `GEN2_TARGET_ARCHITECTURE.md`;
- `GEN2_CANONICAL_DATA_MODEL.md`;
- architecture analysis packages v2 + v3;
- фактические V1 contracts/modules/PostgreSQL migrations 001–045.

---

# 0. Назначение документа

Этот документ отвечает не на вопрос «каким должен быть Домовой», а на вопрос:

> **как перевести существующий Assistant V1 в Gen2, не потеряв уже работающие инварианты, данные, recovery и накопленный опыт.**

Для каждого V1 owner/runtime/table/package используется одно из решений:

- **KEEP** — оставить смысл и основной путь;
- **EXTEND** — расширить существующего owner без параллельного механизма;
- **REWORK** — сохранить owner, но существенно изменить контракт/модель;
- **REPLACE** — создать Gen2 replacement и переключить на него writer/read path;
- **RETIRE** — прекратить новые записи, оставить history/read compatibility, затем удалить;
- **ADD** — новый owner/runtime, которого в V1 нет;
- **COMPAT** — временный compatibility/read model в период миграции.

Gen2 **не является greenfield rewrite**.
Gen2 **не является добавлением второго Assistant рядом с первым**.

---

# 1. Неподлежащие потере V1-инварианты

Следующие смыслы считаются migration constraints, а не деталями реализации:

1. `LLM != Assistant`.
2. `Capability != Authority`.
3. `Observation != Claim != Belief`.
4. `Intent != Goal != Task`.
5. `ActionProposal != AuthorizedAction != ActionAttempt != Outcome`.
6. External mutation проходит только через `Authority -> Commit -> Executor`.
7. `UNKNOWN_OUTCOME` запрещает blind retry возможного повторного эффекта.
8. Только canonical owner пишет canonical state.
9. Cross-owner direct DB write запрещён.
10. Prospective future relevance остаётся canonical в Continuity.
11. Scheduler/wake mechanism не становится владельцем обязательства.
12. Human correction не переписывает прошлое молча.
13. Raw evidence отделено от derived interpretation.
14. Search/vector/cache/context являются rebuildable projections.
15. Provider/model types не проникают в domain owners.
16. Work/Agent execution переживает процесс через durable state/checkpoints.
17. Producer и evaluator/verifier могут быть независимыми.
18. Self-development проходит evidence/proposal/isolation/verification/canary/promotion/rollback.
19. Secret value не является обычной памятью/настройкой/context excerpt.
20. При неполных данных состояние остаётся `UNKNOWN/PARTIAL`, а не угадывается.

Если Gen2 task требует нарушить один из этих пунктов, это не implementation detail: нужен новый архитектурный ADR с явным изменением Конституции.

---

# 2. PRE-GEN2 — обязательная фиксация текущей разработки

**Это выполняется до первой строки Gen2 implementation.**

## 2.1 Цель

Получить единственную, воспроизводимую точку `GEN2_BASE_COMMIT`, в которой:

- все актуальные открытые изменения сохранены;
- ничего не потеряно через reset/discard;
- текущие ветки сведены в основной поток;
- `main` отражает фактическое состояние проекта перед архитектурной миграцией;
- есть tag для полного возврата к V1 baseline.

## 2.2 Последовательность

```text
git status
-> inventory modified/untracked work
-> отделить secrets/build garbage/generated temp
-> FAST baseline gate
-> commit актуальных изменений в их ветках
-> push рабочих веток where needed
-> controlled merge в main
-> resolve conflicts preserving both valid changes
-> FAST gate on main
-> push main
-> record GEN2_BASE_COMMIT
-> tag domovoy-pre-gen2-<date>
-> push tag
```

### Нельзя

- `git reset --hard` неизвестной работы;
- discard чужих/старых незакоммиченных изменений;
- force-push `main`;
- «почистить» файлы без понимания их происхождения;
- включать secrets/tokens/passwords/build artifacts в baseline commit.

Если FAST baseline не проходит:

1. сохранить текущую работу commit'ом/backup branch;
2. исправить baseline;
3. только после зелёного FAST gate делать merge/tag.

## 2.3 PRE-GEN2 FAST gate

Не запускать многосуточный full suite.

Минимум:

- compile затронутых packages;
- targeted baseline tests для текущего diff;
- `devctl preflight`;
- `devctl check-diff`/эквивалент текущей задачи;
- быстрый architecture check;
- `git diff --check`.

Full V1 suite используется только если baseline имеет неизвестное состояние или merge затронул критические owner boundaries.

---

# 3. Закон миграции writer/read path

## 3.1 Один canonical writer

В каждый момент у semantic concept есть **ровно один canonical writer**.

Запрещён переход:

```text
V1 canonical writer -> dual write V1 + Gen2 as two truths
```

Разрешены:

### A. In-place extension

Один owner/table family расширяется новыми revisioned полями/таблицами.

### B. Shadow projection

Gen2 projection строится из V1 canonical state, но не является writer.

### C. Controlled cutover

```text
V1 writer
-> backfill Gen2
-> shadow read/equivalence
-> freeze V1 writer for this concept
-> switch canonical writer to Gen2
-> V1 becomes read-only compatibility projection
-> observe
-> retire compatibility path
```

## 3.2 Rollback

Rollback должен возвращать:

- executable/runtime version;
- active writer pointer;
- schema compatibility;
- read path.

Rollback не должен требовать «удалить уже записанные Gen2 данные».
Новые Gen2 rows остаются historical/candidate evidence и могут быть проигнорированы старым V1.

## 3.3 No destructive migration first

На первом этапе запрещать:

- `DROP TABLE`;
- destructive column rewrite;
- reuse старого поля с новым смыслом;
- ID remapping без lineage;
- переписывание raw evidence;
- массовое удаление old state после cutover.

Retirement — отдельная поздняя задача после observation window.

---

# 4. Owner-level migration matrix

| V1 area | Gen2 decision | V1 owner | Gen2 owner | Основной способ |
|---|---|---|---|---|
| Identity | **KEEP** | Identity | Identity | in-place, минимальные расширения |
| Authority/Scope | **KEEP + CLARIFY** | Authority | Authority | старый Scope становится AuthorityScope |
| Interaction | **KEEP + EXTEND** | Interaction | Interaction | сохранить append-only ingress |
| PersonalMemory | **REPLACE/RETIRE** | Interaction projection | no Memory owner | shadow retrieval -> compatibility retire |
| Situation project focus | **REWORK/REPLACE** | Situation | Situation | Focus V2 parallel tables + cutover |
| Project registry/aliases | **REPLACE** | Situation | World | backfill referents/aliases |
| World referents/schema | **ADD** | — | World | new owner, low-risk first |
| Epistemic truth bundles | **REWORK/REPLACE** | Epistemics | Epistemics | normalize evidence/claim/assessment |
| Experience/Reflection | **EXTEND** | Epistemics | Epistemics | in-place/versioned extension |
| Goals/Tasks/Plans | **EXTEND** | Work | Work | retain IDs + add context/freshness/risk refs |
| Long-running Work | **EXTEND** | Work | Work | reuse AgentRun/Checkpoint/Graph |
| Continuity | **KEEP + EXTEND** | Continuity | Continuity | preserve prospective semantics |
| Capability registry | **KEEP + EXTEND** | Capability | Capability | preserve provider/implementation registry |
| Skill | **REWORK/EXTEND** | Capability | Capability | migrate SkillProfile -> Skill revisions |
| Reflex | **ADD** | FastPath prototype | Capability | explicit new lifecycle |
| Dynamic Configuration | **ADD + ENV migration** | runtime ENV | Configuration | import -> shadow resolve -> cutover |
| Secrets | **KEEP** | platform secrets | platform secrets | only SecretRef in Config/Memory |
| SELF | **ADD** | distributed evidence | SELF | evidence-only first |
| Commit | **KEEP + EXTEND** | Commit | Commit | transition ledger + execution receipt |
| World outcome verification | **ADD/EXPAND** | partial Experience | Epistemics | separate receipt from verified outcome |
| Artifact/raw memory | **KEEP + EXTEND** | Artifact | Artifact | preserve lineage, add segmentation |
| Context Compiler | **REWORK** | cognitive contract/worker | no owner | V2 compiler over retrieval lanes |
| Memory Retrieval | **ADD projection fabric** | ad-hoc | no owner | rebuildable projection schemas |
| Core runtime | **REWORK composition** | runtime | runtime | shrink giant orchestration function |
| Cognitive worker | **KEEP + EXTEND** | no canonical owner | no owner | replaceable reasoning |
| Research runtime | **REWORK/EXTEND** | Epistemics adapter | no new owner | freshness/revalidation integration |
| Work graph runtime | **KEEP + EXTEND** | Work runtime | Work runtime | long-job semantics |
| Supervisor/Lifeboat | **ADD** | — | runtime only | independent release/recovery plane |

---

# 5. Identity — KEEP

## 5.1 Current V1

Paths:

- `contracts/identity/**`
- `modules/identity/domain/**`
- `adapters/postgres/identity_repository.go`
- migration `001_bootstrap_creator_authority.sql`

Current tables:

- `identity.actors`
- `identity.principals`
- `identity.principal_bindings`

## 5.2 Gen2 target

Identity сохраняет:

- Actor identity;
- Principal identity;
- PrincipalBinding;
- authentication/session binding references.

World objects не заменяют Principal/Actor.

## 5.3 Migration

**KEEP in-place.**

Не переносить Identity в World.

Допустимые будущие расширения:

- identifier history;
- aliases/locators linked to identity;
- person/world-object link through typed reference, но ownership Identity остаётся.

## 5.4 Cutover / rollback

Cutover не требуется.

## 5.5 Tests

FAST:
- existing identity binding/session tests.

MILESTONE:
- principal isolation при появлении World/ContextScope.

---

# 6. Authority — KEEP, Scope semantic split

## 6.1 Current V1

Paths:

- `contracts/authority/**`
- `modules/authority/domain/**`
- `adapters/postgres/authority_repository.go`
- migration `001_bootstrap_creator_authority.sql`

Tables:

- `authority.scopes`
- `authority.authority_grants`

`scope_id` также используется во многих V1 rows.

## 6.2 Problem

V1 Core слово `Scope` охватывает слишком много: authority + project/context.

Gen2 разделяет:

- **AuthorityScope** — где действует grant;
- **ContextScope** — где/над чем сейчас работаем.

## 6.3 Migration decision

**KEEP Authority tables. REINTERPRET explicitly as AuthorityScope; do not repurpose their rows.**

DB column `scope_id` может физически остаться именем `scope_id` в V1 tables, но Go contracts нового кода должны использовать distinct `AuthorityScopeID`.

ContextScope создаётся в `situation`, не в `authority`.

## 6.4 Compatibility

Existing:

- `work.tasks.scope_id`;
- `work.goals.scope_id`;
- `continuity.prospective_items.scope_id`;
- `commit.*scope_id/task_scope_id`;
- `situation.focus_bindings.scope_id`

считаются references на **AuthorityScope**, пока явно не мигрированы.

ContextScope добавляется отдельной ссылкой, не заменяет эти значения.

## 6.5 Risk

Самая опасная ошибка Gen2 — начать использовать old `authority.scope_id` для Company/DB/Project filtering.

Запретить architecture lint'ом после ADR-G2-001.

---

# 7. Interaction — KEEP append-only ingress, EXPAND channels

## 7.1 Current V1

Paths:

- `contracts/interaction/types.go`
- `modules/interaction/domain/chat.go`
- `semantics.go`
- `travel.go`
- `task_decomposition.go`
- `personal_memory.go`
- `adapters/postgres/interaction_repository.go`

Tables:

- `interaction.conversations`
- `interaction.utterances`
- `interaction.original_human_intents`
- `interaction.relations`
- `interaction.utterance_interpretations`
- `interaction.project_references`
- `interaction.semantic_candidates`
- `interaction.semantic_candidate_capability_hints`

## 7.2 Keep

Keep canonical:

- Conversation;
- HumanUtterance;
- OriginalHumanIntent;
- correction/supersede/clarify relations;
- interpretation candidates.

`utterances` remain append-only source evidence.

## 7.3 Extend

`channel` currently DB-checks `WEB_CHAT`.
Gen2 should allow typed ingress:

- web chat;
- speech transcript;
- image/document input;
- device/sensor-derived human interaction where appropriate.

Raw audio/image stays Artifact, not large inline Interaction text.

## 7.4 ProjectReference migration

`interaction.project_references` is **legacy project-centric semantic output**.

Target:

- contextual referents become typed World refs / Focus signals;
- table retained read-only for V1 historical data;
- new Gen2 writes use generic typed context-reference contract, not arbitrary `project_id`.

Do not delete historical project references.

## 7.5 PersonalMemory migration

See next section.

---

# 8. PersonalMemory V1 — REPLACE then RETIRE

## 8.1 Current V1

`modules/interaction/domain/personal_memory.go`

Important positive property:

> PersonalMemory is explicitly a rebuildable projection over HumanUtterance history, not canonical truth.

Current limitations:

- rescans utterances;
- extracts only current location and preferences;
- truncates preferences;
- emits `ContextText`;
- no ContextScope/World refs/freshness/contradiction/negative experience.

## 8.2 Gen2 destination

There is **no new Memory owner**.

Replacement:

```text
canonical owners
-> retrieval projections
-> lane retrieval
-> Context Compiler V2
```

Human preferences/statements remain source evidence in Interaction; structured epistemic interpretations can live in Epistemics.

## 8.3 Migration stages

### Stage PM-1 — freeze semantics

Do not add new permanent fact kinds to `PersonalMemory`.

Only bug fixes allowed.

### Stage PM-2 — shadow retrieval

Build retrieval documents from existing:

- HumanUtterances;
- Epistemics evidence;
- Experience;
- Work/Continuity;
- Capability.

Compare produced context with current `ContextText` on existing household scenarios.

### Stage PM-3 — read cutover

Core chat uses Context Compiler V2 bundle.
`PersonalMemory.ContextText()` remains compatibility fallback.

### Stage PM-4 — retire

After MILESTONE memory validation:

- no new call sites to `CompilePersonalMemory`;
- function kept one release only for rollback;
- then remove code, not utterance history.

## 8.4 Rollback

Switch Context Compiler feature flag/read strategy to V1 compatibility projection. No data rollback required.

---

# 9. Situation — REWORK to Focus V2

## 9.1 Current V1

Paths:

- `contracts/situation/types.go`
- `modules/situation/domain/focus.go`
- `adapters/postgres/situation_repository.go`

Tables:

- `situation.focus_bindings`
- `situation.projects`
- `situation.project_aliases`
- `situation.active_project_focus`

Current concepts are strongly project/workspace-oriented.

## 9.2 Gen2 target

Situation owns:

- `ContextScope`;
- `FocusFrame`;
- `FocusTransition`;
- `FocusStack/head`;
- confidence/provenance;
- active goal/task refs;
- typed World refs;
- runtime/session binding.

It does **not** own World object definitions.

## 9.3 Data migration

Create new table family:

- `situation.context_scopes`
- revisions where required;
- `situation.focus_frames`
- `situation.focus_frame_revisions`
- `situation.focus_transitions`
- `situation.focus_heads`
- optional `focus_stack_view` as projection.

Backfill:

- each `active_project_focus` -> FocusFrame with project WorldRef after World project import;
- `focus_bindings` -> runtime binding + active goal/task/AuthorityScope references;
- provenance/confidence preserved exactly.

## 9.4 Project registry move

`situation.projects` and `situation.project_aliases` stop being canonical after World cutover.

They become:

- `WorldObject(kind=PROJECT/ACTIVITY as applicable)`;
- `WorldAlias`.

Important: do not assume every historical project is a long-lived Project. Migration records old semantic class as `legacy_project` metadata until explicit reclassification.

## 9.5 Writer cutover

1. Create World project referents.
2. Create Focus V2 schema.
3. Backfill FocusFrames.
4. Shadow Focus V2 resolver.
5. Compare current `ActiveProjectFocus` decisions.
6. Switch Situation canonical writer to Focus V2.
7. Build `active_project_focus` compatibility projection if old endpoints still need it.
8. Stop V1 project-focus writes.
9. Later retire old project tables only after no callers.

## 9.6 FAST

- explicit focus selection;
- no cross-company/database leak;
- same V1 project command resolves equivalently;
- focus stack push/pop;
- no use of request text by low-level runtime resolver where prohibited.

## 9.7 MILESTONE

- Company A/B same UNF names;
- temporary diversion then return;
- restart persistence;
- old project endpoints compatibility.

---

# 10. World — ADD narrow bounded context

## 10.1 V1 source

No general World owner.

Inputs for initial backfill exist in:

- Situation project registry;
- explicit Interaction references;
- selected configured systems/devices later;
- Identity links only as references.

## 10.2 First Gen2 responsibility

World initially owns only:

- `WorldObject`;
- kind definitions;
- aliases;
- typed `FacetDefinition`;
- typed `RelationDefinition`;
- identity-resolution decisions/lineage.

World **does not own factual truth of facet values**.

Actual observations/claims about objects remain Epistemics.

## 10.3 Migration

Add schema/role `world`.

Initial seed:

- current Situation projects -> World objects + aliases;
- only deterministic, reversible import.

Do not migrate arbitrary chat nouns into World automatically.

## 10.4 Safety

No `SaveEntity(map[string]any)`.
No universal values table.
No cross-owner FK.

## 10.5 Cutover

World object creation can be enabled before Focus writer cutover.
Situation consumes WorldRef contracts, never SQL joins World tables.

---

# 11. Epistemics truth data — REWORK

## 11.1 Current V1

Paths:

- `contracts/epistemics/**`
- `modules/epistemics/domain/truth.go`
- `modules/epistemics/domain/research.go`
- `modules/epistemics/application/**`
- `adapters/postgres/epistemics_repository.go`

Important V1 table:

- `epistemics.truth_bundles`

It stores Source/Snapshot/Excerpt/Observation/Claim/Belief/Citation in one denormalized canonical-looking row.

## 11.2 Problem

Gen2 needs:

- independent immutable evidence;
- structured Proposition;
- multiple Claims against same proposition;
- multiple versioned BeliefAssessments;
- contradiction/historical applicability;
- general freshness/volatility/version binding.

A single truth bundle cannot be long-term canonical representation.

## 11.3 Target

New table families:

- `sources`
- `source_snapshots`
- `source_excerpts`
- `observations`
- `propositions`
- `claims`
- `belief_assessments`
- `belief_heads`
- source reliability records
- world outcome assessments.

## 11.4 Backfill

Deterministically split every `truth_bundles` row:

```text
source_id -> Source
snapshot_id -> SourceSnapshot
excerpt_id -> SourceExcerpt
observation_id -> Observation
claim_id/statement -> Proposition + Claim
belief_id -> BeliefAssessment
citation fields -> evidence links
```

Preserve existing IDs where their semantic meaning matches.
Where V1 ID combines semantics, create new stable ID and record `legacy_ref`.

No old truth row is deleted.

## 11.5 Cutover

1. Gen2 normalizer/backfill.
2. Rebuild count/digest verification.
3. New research writes Gen2 normalized records only.
4. `truth_bundles` becomes compatibility view/projection or read-only legacy.
5. Old read API served from Gen2 projection.
6. Retire direct bundle writer.

## 11.6 Rollback

Keep V1 reader available during observation.
If writer rollback required, convert only new Gen2 research results through explicit compatibility writer if semantics are lossless; otherwise stop writes and return typed migration block rather than silently dropping information.

---

# 12. Freshness / volatility — ADD inside Epistemics, not permanent stale flag

## 12.1 Existing V1

Research snapshots already have `captured_at` and coarse freshness.

## 12.2 Gen2

Add:

- TemporalApplicability;
- VolatilitySpec;
- VersionBinding;
- last verification evidence;
- TaskFreshnessRequirement;
- computed FreshnessAssessment.

## 12.3 Migration

Existing `snapshot_freshness` is imported as **historical assessment evidence**, not as eternal truth.

Do not add a universal mutable column `is_stale`.

Freshness is calculated at retrieval/decision time relative to current task.

---

# 13. Episode — ADD derived episodic memory

Episode is a **derived/versioned Epistemics construct**, not raw source replacement.

Initial Episode builder can group:

- utterances;
- work goals/tasks;
- relevant actions/outcomes;
- artifacts;
- temporal proximity.

No V1 data deletion.

Episode projections are rebuildable; stronger future extractors can supersede old episode revisions.

---

# 14. Experience/Reflection — EXTEND, preserve V1 records

## 14.1 Current

Tables:

- `epistemics.system_expectations`
- `epistemics.experience_records`
- `epistemics.reflection_candidates`

Current Experience already references:

- original intent;
- source utterance;
- context refs;
- help method;
- capability;
- skill;
- expected/actual outcome;
- user correction;
- verification evidence.

This is a strong Gen2 foundation.

## 14.2 Migration

Do not replace V1 experience IDs.

Add V2 expressiveness through versioned extension/linked records:

- problem pattern;
- attempt;
- why attempted;
- applicability/conditions;
- environment/version bindings;
- success/failure explanation;
- reusable lesson candidate;
- positive/negative classification.

Avoid rewriting old rows to invent unavailable details.

Unknown migrated fields remain empty/UNKNOWN.

## 14.3 Reflection

Keep ReflectionCandidate lifecycle and leases.
Extend triggers/evidence links for:

- retrieval miss;
- stale knowledge;
- source trust failure;
- reflex drift;
- self weakness.

---

# 15. Source trust — ADD evidence-backed assessments

Do not write `source.trust = 0.9`.

Add:

- `SourceReliabilityObservation`
- `SourceReliabilityAssessment`

Key dimensions:

- Source;
- Domain/ContextScope;
- freshness;
- observed history;
- evidence basis.

Existing research source metadata seeds Source identity only; no synthetic trust scores during migration.

---

# 16. Work goals/tasks/plans — EXTEND, not replace

## 16.1 Current V1

Paths:

- `contracts/work/**`
- `modules/work/domain/**`
- `modules/work/application/**`
- `adapters/postgres/work_repository.go`

Tables include:

- `work.goals`
- `work.tasks`
- plan candidates/plans/steps;
- capability requirements;
- delegation candidates;
- delegations;
- agent runs/checkpoints/results;
- dispatch queue/leases/callback heads;
- graphs/nodes/edges;
- result candidates/conflicts/synthesis;
- development gates/proposals/scaffolds.

## 16.2 Keep

Preserve stable IDs and lifecycle history.

Do not introduce a second Job/Agent framework.

## 16.3 Extend

Goal/Task gain typed refs where needed:

- ContextScopeRef;
- FocusRef;
- FreshnessRequirement;
- ExpectedQuality;
- risk/cost-of-error/consequence refs;
- budget refs.

Old `project_id/project_display_name` become compatibility fields. New code should prefer Focus/World references.

## 16.4 Migration

New columns/revision tables are additive.

Do not overwrite old `scope_id`; it remains AuthorityScope reference.

---

# 17. LongRunningWork / Investigation — EXTEND Work

## 17.1 Reuse

Reuse:

- WorkGraph;
- AgentRun;
- AgentCheckpoint;
- dispatch queue;
- leases/recovery;
- graph orchestration;
- cancellation;
- synthesis.

## 17.2 Add semantic work state

Add durable `LongRunningWork`/Investigation:

- objective;
- state;
- hypotheses refs;
- attempts;
- findings;
- blockers;
- checkpoint;
- next step;
- budget;
- pause/resume/preempt semantics.

A long task is not represented as one long model request.

## 17.3 Cutover

No cutover of old agent execution required.

New Investigation uses existing Work execution engine underneath.

---

# 18. Perspective / specialist teams — ADD contract, reuse Work Graph

Add `PerspectiveSpec` in Work:

- objectives;
- retrieval profile;
- evaluation criteria;
- capability requirements.

Do not create fixed “DirectorAgent/DesignerAgent” services.

Work Graph nodes may bind a Perspective dynamically.

Team is selected only if Work planner/evaluation predicts value.

---

# 19. Consequence/Risk — ADD Work-owned assessment input

Authority is not risk.

Add `ConsequenceAssessment` owned by Work/planning:

- potential effects;
- reversibility;
- cost of error;
- mitigation;
- simulation/dry-run requirement;
- recommendation for confirmation strength.

Authority consumes approved concrete action context but does not accept Work's risk score as permission.

No hard capability blacklist is introduced as product philosophy.

---

# 20. Continuity — KEEP + additive evolution

## 20.1 Current

Paths:

- `contracts/continuity/**`
- `modules/continuity/**`
- `cmd/continuity-runtime/**`
- `adapters/postgres/continuity_repository.go`

Tables:

- `prospective_items`
- reminder metadata additions;
- `attention_items`
- `human_responses`
- `action_receipts`

## 20.2 Keep

Continuity remains only canonical owner of:

- future relevance;
- commitments/prospective semantics;
- attention;
- human response continuation.

Do not create another scheduler owner in Work/SELF/Memory.

## 20.3 Extend

Current `trigger_at_unix_millis` evolves toward typed `TriggerSpec`:

- absolute time;
- local-time recurrence;
- after-event;
- condition;
- external signal.

Migration rule:

Existing timestamp reminder -> `TriggerSpec.AbsoluteInstant`.

Old column may remain compatibility until all runtime paths read TriggerSpec.

## 20.4 Commitment

If V1 lacks full canonical commitment table, Gen2 adds it under Continuity; existing `commitment_id` references are preserved even when metadata is initially incomplete/UNKNOWN.

---

# 21. Capability registry/model routing — KEEP + EXTEND

## 21.1 Current strength

Current Capability already contains:

- descriptors;
- implementations and revision heads;
- health;
- gaps/acquisition strategies;
- usage observations;
- provider instances/models/bindings;
- qualification/evaluated capabilities;
- performance evidence;
- task evaluations;
- admission leases;
- cost/latency/reliability fields.

Do not replace this with a new “AI router”.

## 21.2 Migration

Extend task strategy selection to consume:

- quality requirement;
- freshness;
- cost of error;
- budget;
- ContextScope;
- Perspective;
- Skill/Reflex availability.

Provider/model records remain Capability-owned.

---

# 22. Skill V1 -> Skill V2 — REWORK in Capability

## 22.1 Current

Tables:

- `capability.skill_profiles`
- `capability.skill_profile_heads`

Current lifecycle:

`CANDIDATE | EVALUATING | VALIDATED | DEGRADED | SUSPENDED | RETIRED`

Already stores supporting and known-failure Experience refs.

## 22.2 Target

Stable Skill identity + explicit Skill revisions:

- applicability spec;
- dependency versions;
- implementation binding;
- evidence;
- revalidation policy;
- promotion history;
- supersedes/merge/split lineage where required.

## 22.3 Migration

Prefer preserving existing `skill_profile_id` as Skill stable ID.

Existing `(skill_profile_id, revision)` rows can be transformed/backfilled into `skill_revisions`.

Do not duplicate active writer:

1. create Skill V2 tables/contracts;
2. backfill current profiles;
3. shadow compare resolver/fast-path decisions;
4. switch Capability skill writer;
5. expose old SkillProfile API as compatibility mapping;
6. retire `skill_profiles` writer;
7. later rename/retire physical tables if valuable.

---

# 23. Reflex — ADD explicit lifecycle

## 23.1 Current precursor

`FastPathDecision` is the correct prototype but not a persistent Reflex identity.

## 23.2 Gen2

Add:

- Reflex stable ID;
- revision;
- derived_from_skill;
- applicability;
- implementation;
- dependency/version bindings;
- evidence;
- ShadowPolicy;
- RevalidationPolicy;
- state.

A Reflex may be code/rule/workflow/small-model path.

## 23.3 Rollback

Any Reflex must have immediate fallback to Skill/reasoning path.

Reflex failure never removes Skill.

---

# 24. Configuration — ADD new owner, migrate ENV gradually

## 24.1 Current V1 evidence

Runtime composition reads many ENV values:

- Postgres hosts/users/passwords;
- runtime URLs;
- cognitive admission limits;
- provider/research endpoints;
- allowed hosts;
- creator username;
- secret backend root;
- tokens/file refs.

Some secrets already correctly use CredentialRef/file resolver.

## 24.2 Gen2 target

New owner `Configuration`:

- `SettingDefinition`;
- revisions/heads;
- `SettingAssignment`;
- ScopeSelector;
- deterministic resolution;
- effective config projection.

Secrets remain in secrets backend and Configuration stores only SecretRef.

## 24.3 Bootstrap set that may remain outside Configuration

Minimal bootstrap only:

- node/runtime identity;
- locator for control-state DB/service;
- root secret resolver locator/credential mechanism;
- emergency listen/bind settings where necessary before DB is reachable.

Everything else should become runtime configuration if it can safely be read after bootstrap.

## 24.4 Migration phases

### CFG-0 inventory

Generate machine-readable inventory of every `os.Getenv/LookupEnv`, its runtime, sensitivity, default and owner.

### CFG-1 definitions

Create typed SettingDefinitions for non-bootstrap values.

### CFG-2 import

Import current non-secret ENV values as scoped assignments.

Map secrets to SecretRefs only.

### CFG-3 shadow resolution

Each runtime computes:

```text
effectiveConfigFromGen2
vs
effectiveConfigFromENV
```

and reports mismatch without changing behavior.

### CFG-4 cutover by runtime

Order recommended:

1. research runtime;
2. cognitive worker;
3. work graph runtime;
4. creator web;
5. core runtime;
6. continuity runtime;
7. commit runtime last.

Commit/Authority mutation path is last because error cost is highest.

### CFG-5 compatibility

ENV becomes read-only emergency fallback for explicitly approved bootstrap keys only.

### CFG-6 retire

Architecture lint rejects new ordinary `os.Getenv` outside bootstrap/config adapters.

---

# 25. SELF — ADD, evidence-only first

## 25.1 Inputs already present

Do not duplicate evidence from:

- Capability usage/performance/model qualification;
- Work task evaluation;
- Epistemics Experience/Reflection;
- human corrections;
- development gates;
- runtime health;
- production outcomes.

## 25.2 First tables

- competence assessments;
- weakness patterns;
- improvement needs;
- dependency assessments;
- learning ledger;
- self-composition snapshots.

## 25.3 First phase limitations

SELF:

- does not execute actions;
- does not grant authority;
- does not mutate Skill automatically;
- does not own Work;
- does not call providers directly.

First version is read/evaluate/propose only.

## 25.4 Promotion

Only after evidence proves usefulness may SELF generate Work improvement proposals through existing governed development path.

---

# 26. Commit — KEEP strict core, EXTEND audit semantics

## 26.1 Current

Paths:

- `contracts/commit/**`
- `modules/commit/**`
- `cmd/commit-runtime/**`
- `adapters/postgres/commit_repository.go`

Tables:

- `commit.authorized_actions`
- `commit.authorized_action_envelopes`
- `commit.action_attempts`

Current code already separates authorization/execution/reconciliation and returns UNKNOWN_OUTCOME.

## 26.2 Keep unchanged in meaning

No Gen2 cognitive/memory/world feature gets direct mutation access.

## 26.3 Extend

Add:

- append-only ActionAttemptTransition ledger;
- explicit ExecutionReceipt;
- stronger idempotency correlation where missing;
- link to later Epistemics WorldOutcomeAssessment.

ExecutionReceipt means:

> executor reported/observed this attempt result

It does not automatically mean:

> desired world state is verified.

## 26.4 Migration

In-place additive.

No writer cutover required.

---

# 27. Outcome verification — EXPAND Epistemics

After significant mutation:

```text
ActionAttempt
-> ExecutionReceipt
-> read-only observation
-> WorldOutcomeAssessment
```

Do not move verified world truth into Commit.

For actions where independent verification is impossible, assessment remains `UNKNOWN/PARTIAL/PROVISIONAL`.

---

# 28. Artifact — KEEP + EXPAND raw memory substrate

Current Artifact contracts are limited but correct boundary.

Gen2 expands:

- Artifact stable ID/version;
- lineage;
- raw external media references;
- SegmentRef;
- future reprocessing lineage.

Large audio/video/document content does not go into Epistemics rows or model context wholesale.

Embeddings/transcripts/summaries are projections/derived records linked to raw Artifact version.

---

# 29. Context Compiler V1 -> V2 — REWORK, no owner

## 29.1 Current

`contracts/cognitive/context_compiler.go`

Good properties:

- provider-neutral;
- deterministic;
- DataPolicy aware;
- excludes secret/unknown sensitivity;
- byte budget;
- explicit omissions.

## 29.2 V2

Inputs include:

- current Focus/ContextScope;
- Task/Goal;
- target model context budget;
- task freshness requirement;
- risk/cost of error;
- candidate lanes:
  - current conversation;
  - relevant knowledge;
  - positive experience;
  - negative experience;
  - active commitments;
  - skills/reflexes;
  - contradiction evidence;
  - source provenance.

Add `ContextAssemblyTrace`.

## 29.3 Migration

Keep current `CompileContext` semantics as low-level final packer.

Build V2 orchestrator around it rather than replacing safe data-policy checks.

Eventually old `ContextCompileInput{Candidates, DataPolicy, MaxBytes}` becomes internal stage.

---

# 30. Memory Retrieval Fabric — ADD projections, no canonical owner

## 30.1 Projection stores

Create rebuildable projection schema(s):

- retrieval documents;
- World alias index;
- temporal index;
- experience index;
- current-knowledge index;
- embeddings.

## 30.2 Builder inputs

Builders read owner APIs/events/owner-local exports; they do not directly become cross-owner canonical DB joins.

## 30.3 Retrieval order

1. hard principal/realm/scope/version filters;
2. exact entity/alias matching;
3. temporal relevance;
4. graph/relation candidate expansion where available;
5. semantic/vector candidate retrieval;
6. positive experience lane;
7. negative experience lane;
8. contradiction pass;
9. rerank against task/context budget.

## 30.4 Migration

Start as shadow only.
No user response depends solely on new retrieval before MILESTONE validation.

---

# 31. Core runtime — REWORK composition, do not make God orchestrator

## 31.1 Current problem

`cmd/core-runtime/main.go` is a large composition root/HTTP handler that directly wires many repositories, runtime clients, semantic heuristics and response functions.

Gen2 adds more owners; adding all logic to this file would make architecture unmaintainable.

## 31.2 Migration

Do not rewrite entire runtime at once.

Extract by bounded responsibility:

- bootstrap/composition;
- authenticated interaction ingress;
- focus assembly;
- context retrieval/compile;
- capability strategy resolution;
- Work submission;
- response composition.

Each extracted package depends on contracts, not other owners' repositories.

Core runtime may orchestrate APIs but must not become canonical owner.

## 31.3 Cutover

Handler-by-handler, preserving HTTP compatibility.

Do not change routing + data migration + UX in one commit when avoidable.

---

# 32. Cognitive worker — KEEP replaceable cognition

Current:

- interpretation;
- gateway;
- admission;
- discovery;
- model qualification;
- multimodal handling;
- task evaluation.

Gen2:

- consume ContextBundle V2;
- support iterative memory tool/query;
- Perspective contract;
- long-running task handoff to Work rather than holding request open.

No canonical DB ownership added.

---

# 33. Research runtime — REWORK/EXTEND

Current Research already writes/returns Epistemics evidence and has connector restrictions.

Gen2:

- use Source/SourceSnapshot/Observation normalized model;
- explicit TaskFreshnessRequirement;
- active revalidation request;
- distinguish no-access vs stale-memory fallback;
- preserve partial/unknown.

Research connectors remain adapters; no new Research truth owner.

---

# 34. Work graph runtime — KEEP/EXTEND

Keep durable queue/lease/recovery/graph/synthesis.

Add:

- LongRunningWork binding;
- budget/preemption;
- Perspective per node;
- evidence-linked Finding/Attempt;
- strategy escalation.

Do not create parallel “background task service” with separate canonical jobs.

---

# 35. Continuity runtime — KEEP

Keep:

- due processing;
- attention;
- human response;
- internal executor transition semantics.

Extend trigger adapter model behind Continuity contracts.

No in-memory durable timer.

---

# 36. Commit runtime — KEEP, migrate configuration last

Keep strict isolation.

Gen2 changes should be minimal until:

- Configuration stable;
- Supervisor available;
- receipt/outcome contracts tested.

Commit runtime is one of last runtimes to remove non-bootstrap ENV compatibility.

---

# 37. Creator Web — KEEP UX surface, reduce admin dependence

Creator Web remains:

- chat;
- attachments;
- diagnostic/emergency surfaces.

Primary configuration operation should become conversational.

Do not delete diagnostic pages; they are useful when conversational layer is degraded.

UI changes are not blockers for backend Gen2 foundation.

---

# 38. PostgreSQL adapters — REWORK per owner, no generic repository

Current `adapters/postgres/*_repository.go` correctly separates owner repositories.

Keep this pattern.

Add:

- `WorldRepository`;
- `ConfigurationRepository`;
- `SelfModelRepository`;
- projection builders/stores separately.

Do not create one generic `EntityRepository`/`MemoryRepository`.

Migration-specific backfill code should live under explicit tooling/migration packages and be removable after cutover.

---

# 39. Runtime health / Supervisor — ADD independent Lifeboat

Existing `runtime/health` remains health primitive.

New Supervisor/Lifeboat is a separate minimal runtime/control plane:

- current active release;
- last-known-good release;
- start candidate;
- health window;
- switch;
- rollback;
- restart recovery.

It does not own Assistant semantic state.

It must not require the broken main conversational path to initiate rollback.

---

# 40. V1 migration ledger 001–045

The historical migration files remain immutable history.
Do **not** edit old migration files; Gen2 adds new numbered migrations.

| V1 migration | Gen2 disposition |
|---|---|
| 001 bootstrap creator/authority | **KEEP**; Scope explicitly AuthorityScope |
| 002 continuity prospective | **KEEP/EXTEND**; migrate timestamp to TriggerSpec compatibility |
| 003 situation focus bindings | **REPLACE/RETIRE** after Focus V2 cutover |
| 004 work tasks | **KEEP/EXTEND** |
| 005 commit actions | **KEEP** |
| 006 capability health | **LEGACY KEEP** |
| 007 health v2/projection | **KEEP projection pattern**, may be superseded by newer projection |
| 008 authorized action envelope | **KEEP** |
| 009 continuity action receipts | **KEEP compatibility**, clarify vs Commit ExecutionReceipt |
| 010 notification bindings | **KEEP** |
| 011 notification envelope | **KEEP** |
| 012 cognitive registry | **KEEP/EXTEND** |
| 013 discovery evidence | **KEEP** |
| 014 binding revision heads | **KEEP** |
| 015 interaction foundation | **KEEP/EXTEND channel semantics** |
| 016 human intent project context | **PARTIAL RETIRE**: project registry/focus -> World/Focus V2; historical interaction refs retained |
| 017 work planning | **KEEP/EXTEND** |
| 018 capability resolution | **KEEP/EXTEND** |
| 019 reminder metadata | **KEEP** |
| 020 attention items | **KEEP** |
| 021 notification assistant origin | **KEEP** |
| 022 human responses | **KEEP** |
| 023 experience/reflection/skill | **EXTEND** Experience; **REWORK** Skill V2 |
| 024 agent delegation | **KEEP/EXTEND** |
| 025 delegation attention/verification | **KEEP** |
| 026 attention response outcomes | **KEEP** |
| 027 semantic candidates | **KEEP/EXTEND** contextual refs |
| 028 cognitive provider profile | **KEEP** |
| 029 agent execution persistence | **KEEP** |
| 030 dispatch queue | **KEEP** |
| 031 work graph persistence | **KEEP** |
| 032 reflection leases | **KEEP** |
| 033 cognitive admission leases | **KEEP** |
| 034 epistemics truth bundles | **REPLACE writer; RETAIN legacy read/history** |
| 035 graph dispatch binding | **KEEP** |
| 036 graph synthesis | **KEEP** |
| 037 development gates | **KEEP** |
| 038 development gate privileges | **KEEP** |
| 039 task evaluations | **KEEP/EXTEND Personal Benchmark** |
| 040 task evaluation dispatch | **KEEP** |
| 041 task evaluation payload | **KEEP**, constrain JSON to typed contract payloads |
| 042 agent execution recovery | **KEEP** |
| 043 governed development candidates | **KEEP/EXTEND with expected improvement** |
| 044 graph orchestration snapshot | **KEEP** |
| 045 model qualification observations | **KEEP** |

Historical migrations are evidence. Gen2 migration starts at the next available migration number and never renumbers V1.

---

# 41. New Gen2 schema migration groups

Exact migration numbers are assigned after current repository HEAD is fixed.

Recommended groups:

## G2-A — architecture/bootstrap

- create roles/schemas for `world`, `configuration`, `self_model`, projection writer;
- no user behavior switch.

## G2-B — Focus/World

- World object/type/alias definitions;
- ContextScope/FocusFrame/transitions/heads;
- project backfill tool;
- compatibility read model.

## G2-C — Epistemics normalized evidence

- Source/Snapshot/Excerpt/Observation/Proposition/Claim/Belief;
- freshness/version metadata;
- truth bundle backfill;
- legacy bundle compatibility.

## G2-D — Retrieval/context

- projection schema/index tables;
- retrieval builder checkpoints;
- ContextAssemblyTrace.

## G2-E — Configuration

- definitions/revisions/heads;
- assignments/revisions/heads;
- effective config projection;
- ENV import audit table/tooling if needed.

## G2-F — Skill/Reflex

- Skill V2 revision/head;
- Reflex revision/head;
- shadow/revalidation evidence.

## G2-G — SELF

- assessments;
- weakness;
- learning ledger;
- composition snapshots.

## G2-H — Work/Continuity/Commit additive semantics

- LongRunningWork;
- Perspective;
- ConsequenceAssessment;
- TriggerSpec representation;
- action transition ledger;
- ExecutionReceipt;
- WorldOutcomeAssessment.

## G2-I — retirement markers

No `DROP` initially.
Record deprecated writers/readers and enable architecture lint to prevent new call sites.

---

# 42. Backfill requirements

Every backfill command must be:

- idempotent;
- restartable;
- checkpointed;
- scope-limited;
- dry-run capable;
- counts/digests reported;
- no destructive mutation of source;
- able to resume after process failure.

Backfill status itself is operational migration state, not domain truth.

For large future raw memory, backfill must stream/chunk; never load entire history into one model context.

---

# 43. Feature switches/cutover controls

Gen2 needs explicit operational switches stored outside model prompts.

Examples:

- Focus read strategy: `V1 | SHADOW_V2 | V2`;
- Context strategy: `PERSONAL_MEMORY_V1 | SHADOW_GEN2 | GEN2`;
- Epistemics write strategy: `TRUTH_BUNDLE_V1 | NORMALIZED_G2`;
- Config read strategy per runtime: `ENV | SHADOW_G2 | G2`;
- Skill strategy: `PROFILE_V1 | SHADOW_SKILL_V2 | SKILL_V2`;
- Reflex: `DISABLED | SHADOW | ENABLED`;
- SELF: `OBSERVE_ONLY | PROPOSE`;
- Supervisor release channel.

These switches are migration controls, not long-lived user settings.
After retirement they are removed.

---

# 44. Migration observation windows

Do not promote based only on unit tests.

For each cutover define an observation window appropriate to risk.

Low-risk retrieval:

- shadow comparison over representative real turns.

Focus:

- enough turns to include explicit/inferred switches and Company A/B ambiguity.

Configuration:

- runtime restart + missing-config + secret-resolution scenarios.

Skill/Reflex:

- historical replay + shadow production.

Commit:

- reconciliation/unknown-outcome/restart.

No fixed universal duration is required; evidence threshold is task-specific.

---

# 45. Testing strategy during migration

## 45.1 FAST — default Codex loop

Run only:

- changed package compile/tests;
- directly affected contract tests;
- one/few regression cases for the actual gap;
- fast architecture lint for touched boundary;
- migration SQL parse/small repository test when schema touched.

**Do not run `go test ./...` after every edit.**

## 45.2 MILESTONE — after architectural organ is complete

Run:

- all tests of changed owner;
- integration with immediate neighbors;
- migration/backfill equivalence;
- restart/recovery for durable state;
- relevant household scenarios;
- architecture boundary checks.

Suggested milestones:

A. World + Focus V2
B. Epistemics + Retrieval + Context Compiler
C. Configuration + Skill/Reflex + SELF
D. LongRunningWork + Consequence + Outcome + Lifeboat
E. V1 compatibility retirement / Gen2 system integration

## 45.3 FULL — rare

Run only:

- before large architecture phase merge;
- after critical schema migration;
- before production canary;
- before retiring V1 rollback path;
- final Gen2 acceptance.

FULL includes repository-wide test/vet/architecture/recovery/household/multimodal/migration checks.

## 45.4 Test-growth rule

If test code/execution begins consuming substantially more effort than capability implementation without protecting a new material risk:

> stop test expansion and review sufficiency.

Passing tests is evidence; **the task goal is the working architectural capability**.

---

# 46. Runtime migration order

Recommended order is chosen by dependency/risk, not convenience.

```text
0 PRE-GEN2 baseline
1 architecture docs + ADRs + registry generation 2
2 World vocabulary/referents
3 Situation Focus V2
4 Epistemics normalized/freshness
5 Retrieval + Context Compiler V2
6 Configuration foundation
7 Capability Skill V2 + Reflex
8 SELF observe/evaluate
9 Work long-running/perspective/consequence
10 Continuity TriggerSpec extensions
11 Commit receipt/outcome clarification
12 Supervisor/Lifeboat
13 runtime-by-runtime Configuration cutover
14 household/system integration
15 production canary
16 V1 writer/read retirement
```

Why World before Focus: Focus V2 needs stable typed referents.

Why Epistemics before retrieval: retrieval must index canonical evidence, not invent a new truth store.

Why Configuration before deep self-evolution: new Skills/self-written capabilities need scoped typed settings.

Why SELF after Skill/Experience/Capability evidence: SELF must derive assessments from evidence, not empty self-scores.

Why Commit changes late: highest consequence and current V1 boundary is already strong.

---

# 47. Package-level action map

## KEEP mostly unchanged

- `modules/identity/**`
- `modules/authority/**`
- `modules/commit/domain/**` semantic core
- `modules/continuity/domain/human_response.go`
- current Work Graph/lease/recovery semantics
- `platform/ids/**`
- `platform/secrets/**`
- `runtime/health/**`
- model/provider adapters behind Capability/Gateway.

## EXTEND

- `contracts/interaction/**`
- `contracts/epistemics/**`
- `contracts/work/**`
- `contracts/continuity/**`
- `contracts/capability/**`
- `modules/epistemics/**`
- `modules/work/**`
- `modules/continuity/**`
- `modules/capability/**`
- corresponding owner postgres repositories.

## REWORK

- `contracts/situation/**`
- `modules/situation/**`
- `contracts/cognitive/context_compiler.go`
- `cmd/core-runtime/main.go` composition/routing structure
- research persistence path;
- Skill profile API compatibility layer.

## REPLACE/RETIRE

- `modules/interaction/domain/personal_memory.go` as primary memory retrieval;
- Situation project registry as canonical world referent registry;
- ActiveProjectFocus as canonical focus;
- direct `truth_bundles` writer;
- ordinary non-bootstrap ENV reads after Config cutover.

## ADD

- `contracts/world/**`, `modules/world/**`;
- `contracts/configuration/**`, `modules/configuration/**`;
- `contracts/selfmodel/**`, `modules/selfmodel/**`;
- Context retrieval contracts/projection builders;
- Supervisor runtime;
- Reflex contracts/domain.

Exact package names may be adjusted by ADR but semantic owners may not drift silently.

---

# 48. Architecture registry changes

Gen2 needs `semantic_generation: 2`, `architecture_generation: 2` only after ADRs are accepted.

Registry additions:

- World owner/schema;
- Configuration owner/schema;
- SELF owner/schema;
- projection mechanism entry as non-domain owner;
- Supervisor topology as runtime-only.

Registry dependency rules must prevent:

- SELF -> direct owner DB writes;
- World -> Epistemics truth ownership;
- Configuration -> secrets raw values;
- cognitive worker -> canonical writes;
- projection builder -> canonical domain writes;
- Work -> Authority grant mutation.

---

# 49. Known migrations that must not be combined

Avoid one task that simultaneously performs:

### Focus + Memory + Configuration

Too many failure causes; impossible to diagnose.

### Epistemics normalization + model provider change

Would confound truth migration with model quality.

### Skill V2 + Reflex auto-generation

First make Skill V2 stable; Reflex is next layer.

### SELF + autonomous self-code promotion

SELF first observes/evaluates. Existing governed development remains authority path.

### Commit schema + Authority redesign

Authority semantics are not being redesigned in Gen2 foundation.

### Production cutover + V1 table deletion

Retirement occurs after stable observation, never in same promotion.

---

# 50. Rollback map by subsystem

| Subsystem | Rollback target |
|---|---|
| World seed | disable World consumers; V1 project registry remains |
| Focus V2 | switch read to ActiveProjectFocus/FocusBinding |
| Epistemics normalized | legacy truth bundle reader; stop new writer if lossy |
| Retrieval V2 | PersonalMemory/current deterministic context |
| Configuration | approved ENV bootstrap/fallback snapshot |
| Skill V2 | SkillProfile V1 compatibility reader |
| Reflex | disable Reflex, escalate to Skill/reasoning |
| SELF | set OBSERVE_ONLY/off; no canonical dependency |
| LongRunningWork | existing AgentRun/Graph execution |
| TriggerSpec | absolute timestamp compatibility path |
| Outcome verification | Commit receipt remains; world outcome may be UNKNOWN |
| Supervisor candidate | switch last-known-good release |

Rollback must not discard new evidence.

---

# 51. Data retention / retirement rules

Retirement candidates:

- V1 project tables;
- ActiveProjectFocus;
- PersonalMemory compatibility path;
- direct truth bundle writer;
- SkillProfile V1 writer;
- non-bootstrap ENV readers.

Retirement requires all:

1. no active writer;
2. no undocumented reader;
3. MILESTONE/FULL evidence;
4. rollback window completed;
5. data migrated or intentionally retained historical;
6. architecture scan rejects new references;
7. explicit retirement commit/task.

`DROP TABLE` is optional and can be much later.
Logical retirement is more important than immediate physical deletion.

---

# 52. Production transition strategy

Production Gen2 is promoted by subsystem/phase, not by one giant day.

Recommended:

```text
deploy code capable of V1 + shadow Gen2
-> build/backfill Gen2 data
-> observe
-> enable one Gen2 read path
-> observe
-> enable canonical writer
-> observe
-> next subsystem
```

For strict mutation path, prefer:

```text
candidate release
-> health
-> controlled traffic
-> reconciliation smoke
-> promote
```

Supervisor/Lifeboat must exist before the first self-modifying production release that could break main conversational recovery.

---

# 53. Evidence required at each status change

## KEEP

Existing regression/invariant evidence sufficient unless code touched.

## EXTEND

Need targeted tests + backward-compatible read/write evidence.

## REWORK

Need old vs new behavior comparison for overlapping semantics.

## REPLACE

Need:
- backfill;
- shadow/equivalence;
- writer cutover proof;
- rollback proof.

## RETIRE

Need:
- caller inventory;
- no active writer;
- no required read path;
- observation window;
- explicit approval/task.

---

# 54. Migration blockers that must become ADR/task decisions

Before implementation, resolve/accept:

1. AuthorityScope vs ContextScope.
2. World owner and typed schema vocabulary.
3. Epistemics normalized truth/freshness model.
4. Memory retrieval with no Memory owner.
5. Configuration owner/bootstrap boundary.
6. Skill V2/Reflex lifecycle.
7. SELF boundaries.
8. Long-running Work semantics.
9. Consequence/Risk semantics.
10. Supervisor/Lifeboat.
11. ExecutionReceipt vs WorldOutcomeAssessment.
12. Gen2 compatibility/retirement policy.

If an implementation task reaches an unresolved owner conflict, result is `BLOCKED_BY_ARCHITECTURE_GAP`, not a local workaround.

---

# 55. What is deliberately not migrated now

Gen2 foundation leaves interfaces/open vocabulary for:

- ambient microphone streams;
- speaker recognition;
- continuous video;
- TV/speaker output choice;
- home automation;
- robots/vehicles;
- Digital Twin;
- mandatory graph DB;
- automatic compilation of every Skill;
- automatic global Skill rewrite by new model;
- permanent fixed multi-agent staff.

No current Gen2 decision may make these require replacement of strict core semantics later.

---

# 56. Milestone definition for Master Plan

## M0 — Frozen V1 baseline

Result:
- clean/known `main`;
- base commit/tag;
- current work preserved.

## M1 — Semantic substrate

Includes:
- ADRs;
- World;
- ContextScope/Focus V2.

Exit:
- project-centric focus no longer limits new features;
- V1 compatibility works.

## M2 — Memory/Knowledge foundation

Includes:
- Epistemics normalization;
- freshness/volatility;
- Experience V2;
- retrieval fabric;
- Context Compiler V2.

Exit:
- current task receives scoped fresh positive+negative memory;
- V1 PersonalMemory is fallback only.

## M3 — Evolvable behavior

Includes:
- Configuration;
- Skill V2;
- Reflex;
- SELF observe/evaluate.

Exit:
- new capability can define typed scoped settings;
- known solution can become Skill/Reflex;
- quality is evidence-backed.

## M4 — Durable autonomy and self-evolution safety

Includes:
- LongRunningWork;
- Perspective/team;
- Consequence;
- improved Outcome verification;
- Supervisor/Lifeboat.

Exit:
- long tasks survive restart;
- self-change can be candidate-tested-promoted-rolled-back safely.

## M5 — Integrated household Gen2

Includes:
- migration of existing household behavior;
- multi-person/scope tests;
- degraded/local model paths;
- production canary.

## M6 — V1 retirement

Only after stable production evidence.

---

# 57. Handoff to GEN2 Master Plan

Master Plan must convert this map into executable task packets.

For every task packet it must state:

- milestone;
- current owner;
- target owner;
- exact allowed paths;
- exact forbidden/protected paths;
- table/contracts affected;
- writer before task;
- writer after task;
- backfill needed/not needed;
- compatibility strategy;
- rollback;
- FAST gate;
- whether task ends a MILESTONE;
- whether FULL gate is justified;
- dependencies;
- explicit non-goals.

No Codex task may say only:

> «реализуй память Gen2»

or:

> «улучши архитектуру».

Every task must finish one bounded migration step with observable exit criteria.

---

# 58. Final migration verdict

Existing V1 is worth preserving.

**Do not rewrite from zero.**

But the following V1 mechanisms must not remain the long-term foundation:

1. project-only/current `ActiveProjectFocus`;
2. ad-hoc `PersonalMemory` context projection;
3. direct denormalized `truth_bundles` as final epistemic model;
4. ENV as ordinary runtime configuration;
5. implicit FastPath as the only representation of Reflex;
6. distributed self-evaluation without explicit SELF model;
7. absence of independent whole-system rollback supervisor.

The following V1 mechanisms are strategic assets and should survive Gen2:

1. Identity/Principal separation;
2. Authority boundary;
3. Epistemic truth-first distinction;
4. Work durable graph/agents/checkpoints;
5. Continuity prospective/attention;
6. Capability registry/model evidence;
7. Skill positive/negative evidence foundation;
8. Commit/UNKNOWN_OUTCOME/reconciliation;
9. governed self-development gates;
10. secret references;
11. architecture registry/lint/governance.

Итоговая стратегия:

```text
preserve evidence and invariants
-> add Gen2 semantic substrate
-> backfill
-> shadow
-> cut over one owner at a time
-> observe
-> keep rollback
-> retire V1 paths only after proof
```

Это и есть путь от текущего Assistant к развивающемуся Домовому Gen2 без потери уже сделанной работы.