From 1c334fcce66c6730da363b6417b6572ce45c4715 Mon Sep 17 00:00:00 2001 From: Mikhail Date: Tue, 18 Aug 2026 00:19:54 +0300 Subject: [PATCH] chore: consolidate DEV-000074 cold-start continuity governance --- AGENTS.md | 70 +++++++- dev/ACTIVE_TASK.json | 4 +- ...x-project-memory-agents-consolidation.json | 106 ++++++++++++ docs/COLD_START_AND_DURABLE_CHECKPOINT.md | 76 +++++++++ docs/PROJECT_STATUS.md | 16 +- .../dev-000074-cold-start-reconstruction.md | 153 ++++++++++++++++++ 6 files changed, 416 insertions(+), 9 deletions(-) create mode 100644 dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json create mode 100644 docs/COLD_START_AND_DURABLE_CHECKPOINT.md create mode 100644 docs/evidence/dev-000074-cold-start-reconstruction.md diff --git a/AGENTS.md b/AGENTS.md index cf6872a..167ff2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,16 +2,45 @@ You are implementing this repository under a frozen architecture generation. **Capability to edit files is not authority to change architecture.** +## Durable project principles + +- Domovoy is a long-lived personal assistant, not a one-off chatbot or coding helper. +- Current specialization is temporary; architecture is implementation-specific and revisable by approved architecture decisions. +- Codex is an implementation capability, not architectural owner by default. +- Model/provider is implementation infrastructure, not Domovoy identity. +- Human reality claims are only claims until supported. +- Human intent/preferences are strong evidence, even when not external facts. +- UNKNOWN is a valid state and must remain explicit. +- Reversible/low-risk safety is required before irreversible action. +- Deterministic reflex is optimization, not final semantic truth. +- Capability, transport, and implementation are separate concerns. +- Capability usage requires declared evidence and observed capability gap handling. +- LLM cost/brand/availability is evidence, not a blanket truth rule. +- Experience is not learning by itself; only measured behavior change becomes evidence. +- Normal user interaction must stay zero-ops. +- Live configuration and canonical state should be portable and bootstrap-only environment should stay minimal. +- Production continuity must include recovery and provenance across model/binding/config/loader/operator changes. +- Do not overbuild future systems for current milestone. + ## Mandatory startup sequence Before any non-trivial change: -1. Read `architecture/ARCHITECTURE_CONSTITUTION.md`. -2. Read `architecture/CORE_SEMANTIC_MODEL_V1.md`. -3. Read `architecture/architecture-registry.yaml` and `architecture/architecture-registry.json`. -4. Read `development/CODEX_DEVELOPMENT_CONTRACT.md`. -5. Read the active file under `dev/tasks/`. -6. Run `go run ./cmd/devctl preflight -task ` for Tier B+ tasks when available. +1. Inspect git branch, status, and recent ancestry (at least `git status`, `git rev-parse`, `git log -1`). +2. Read `AGENTS.md`. +3. Read `architecture/ARCHITECTURE_CONSTITUTION.md`. +4. Read `architecture/CORE_SEMANTIC_MODEL_V1.md`. +5. Read `architecture/architecture-registry.yaml` and `architecture/architecture-registry.json`. +6. Read `development/CODEX_DEVELOPMENT_CONTRACT.md`. +7. Read `dev/ACTIVE_TASK.json`. +8. Read the current task packet under `dev/tasks/` referenced by `ACTIVE_TASK`. +9. Read relevant accepted ADRs from `architecture/adrs`. +10. Inspect `docs/PROJECT_STATUS.md` and current evidence artifacts for checkpoint continuity. +11. Inspect current runtime evidence/check commands before implementation. +12. Run `go run ./cmd/devctl preflight -task ` for Tier B+ tasks. +13. Then proceed with implementation. + +For a fresh session, this sequence is the required cold-start reconstruction path and must be documented in the task checkpoint. If documents conflict, authority order is: @@ -72,3 +101,32 @@ State: - assumptions; - findings not changed; - gaps or limitations. + +## Session reconstruction checkpoint (Durable memory) + +Before leaving a DEV, include machine-readable checkpoint facts in: + +- `dev/ACTIVE_TASK.json` +- active task packet under `dev/tasks/` +- `docs/PROJECT_STATUS.md` +- `docs/COLD_START_AND_DURABLE_CHECKPOINT.md` + +The checkpoint must explicitly carry: + +- `STATUS` +- `CURRENT_PHASE` +- `COMPLETED` +- `IN_PROGRESS` +- `NOT_STARTED` +- `BLOCKERS` +- `IMPORTANT_FINDINGS` +- `EVIDENCE_OBTAINED` +- `LAST_VERIFIED_COMMIT` +- `NEXT_ACTION` + +No product behavior or canonical semantic changes are required for this milestone. + +The fresh-session recovery procedure and evidence expectations are documented in: +`docs/COLD_START_AND_DURABLE_CHECKPOINT.md`. + +Execution-window exhaustion is continuation, not failure; do not mark a task done only because a session ends. diff --git a/dev/ACTIVE_TASK.json b/dev/ACTIVE_TASK.json index 3052249..d44c620 100644 --- a/dev/ACTIVE_TASK.json +++ b/dev/ACTIVE_TASK.json @@ -1,5 +1,5 @@ { - "task_file": "dev/tasks/DEV-000072-semantic-interpretation-deferral-boundary.json", - "task_id": "DEV-000072", + "task_file": "dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "task_id": "DEV-000074", "task_revision": 1 } diff --git a/dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json b/dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json new file mode 100644 index 0000000..49c489f --- /dev/null +++ b/dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json @@ -0,0 +1,106 @@ +{ + "task_id": "DEV-000074", + "task_revision": 1, + "architecture_revision": "arch-generation-1", + "base_repo_revision": "fd59b93463bea80459375ecb28864c03ec3efc42", + "risk_tier": "E", + "intent": "Consolidate Codex development memory and cold-start continuity so a fresh session can reconstruct active milestone, boundaries, tests, and next action from repository artifacts only. Do not change Domovoy product behavior; do not change deployment runtime configuration.", + "requirement_ids": [ + "DEV-000061 governance continuity", + "FOUNDATION_EXIT_AUDIT checkpoint continuity", + "Cold-start reconstruction from repository only", + "No product behavior regression", + "Durable continuation fields" + ], + "allowed_change_scope": { + "modules": [], + "paths": [ + "AGENTS.md", + "docs/PROJECT_STATUS.md", + "docs/COLD_START_AND_DURABLE_CHECKPOINT.md", + "docs/evidence/dev-000074-cold-start-reconstruction.md", + "dev/ACTIVE_TASK.json", + "dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json" + ] + }, + "forbidden_change_scope": { + "paths": [ + "architecture/ARCHITECTURE_CONSTITUTION.md", + "architecture/architecture-registry.yaml", + "architecture/architecture-registry.json", + "architecture/adrs/**", + "security/**", + "modules/**", + "contracts/**", + "adapters/**", + "cmd/**", + "deploy/**", + ".gitea/**", + "ci/**" + ] + }, + "allowed_architecture_delta": { + "new_cross_module_dependencies": 0, + "new_canonical_owners": 0, + "new_privileges": 0, + "new_third_party_dependencies": 0, + "new_provider_adapters": 0, + "new_database_owner_roles": 0 + }, + "contracts": { + "consume": [], + "may_change": [] + }, + "semantic_owner": "governance", + "canonical_state": [ + "AGENTS.md contains the durable cold-start startup sequence and checkpoint rules.", + "Checkpoint continuity is preserved in docs/PROJECT_STATUS plus reconstructed durable checkpoint fields." + ], + "state_transitions": [ + "Fresh session -> read required artifacts -> reconstruct active task and phase", + "Checkpoint update -> clear/record blockers -> define next action", + "Preflight and checks -> produce final continuity status and evidence" + ], + "side_effects_and_privileges": [ + "No direct external mutation", + "No runtime/runtime-host configuration changes", + "No production actions" + ], + "persistence_and_migrations": [ + "No database migration", + "No schema or privilege change", + "No canonical ownership change" + ], + "failure_retry_restart": [ + "If required startup artifacts are missing, return BLOCKED_BY_MISSING_CAPABILITY and update checkpoint.", + "If checkpoint and active task disagree, BLOCKED_BY_SPEC_GAP and require a corrective checkpoint update.", + "Execution-window exhaustion is continuation state, not failure." + ], + "assumptions": [ + "Foundation architecture and ADR set is already accepted.", + "No production behavior change is authorized in this milestone." + ], + "acceptance_scenarios": [ + "Fresh session reconstructs active DEV, phase, blockers, and next action from artifacts alone.", + "ACTIVE_TASK points to DEV-000074 task packet after switching.", + "AGENTS cold-start checklist remains practical and non-duplicative.", + "Docs checkpoint explicitly records durable status with explicit evidence references.", + "Architecture/diff checks pass.", + "No changed files outside governance/documentation scope." + ], + "required_tests": [ + "go test ./...", + "go vet ./...", + "go run ./cmd/devctl preflight -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "go run ./cmd/devctl check-architecture", + "go run ./cmd/devctl check-diff -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json" + ], + "terminal_gap_states": [ + "BLOCKED_BY_SPEC_GAP", + "BLOCKED_BY_ARCHITECTURE_GAP", + "BLOCKED_BY_MISSING_CAPABILITY", + "BLOCKED_BY_CONFLICT", + "REQUIRES_MIGRATION_DECISION" + ] +} diff --git a/docs/COLD_START_AND_DURABLE_CHECKPOINT.md b/docs/COLD_START_AND_DURABLE_CHECKPOINT.md new file mode 100644 index 0000000..fd558bb --- /dev/null +++ b/docs/COLD_START_AND_DURABLE_CHECKPOINT.md @@ -0,0 +1,76 @@ +# Cold start reconstruction and durable checkpoint guidance + +## 1) Fresh session reconstruction (no chat dependency) + +Any new Codex session must reconstruct active state using repository artifacts only: + +1. `git status`, `git rev-parse --abbrev-ref HEAD`, `git log -1 --oneline` +2. `AGENTS.md` +3. `architecture/ARCHITECTURE_CONSTITUTION.md` +4. `architecture/CORE_SEMANTIC_MODEL_V1.md` +5. `architecture/architecture-registry.yaml` +6. `architecture/architecture-registry.json` +7. `development/CODEX_DEVELOPMENT_CONTRACT.md` +8. `dev/ACTIVE_TASK.json` +9. active task packet referenced by `dev/ACTIVE_TASK.json` +10. relevant accepted ADRs +11. `docs/PROJECT_STATUS.md` +12. relevant evidence artifacts in `docs/evidence/**` and tests configured for current task + +The objective is to restore: + +- what Domovoy is and current implementation state; +- active DEV/task and scope; +- architecture boundaries and governance stack; +- last verified commit and next action. + +No external chat context is required. + +## 2) Canonical durable checkpoint fields + +Current work checkpoints are represented through: + +- `docs/PROJECT_STATUS.md` checkpoint blocks per DEV-id. +- `dev/ACTIVE_TASK.json` for active packet identity. +- active task packet fields and scope. + +Required conceptual fields: + +- `STATUS` +- `CURRENT_PHASE` +- `COMPLETED` +- `IN_PROGRESS` +- `NOT_STARTED` +- `BLOCKERS` +- `IMPORTANT_FINDINGS` +- `EVIDENCE_OBTAINED` +- `LAST_VERIFIED_COMMIT` +- `NEXT_ACTION` + +No single file must hold all facts; continuity is reconstructed from the three authoritative artifacts above plus repository evidence. + +## 3) Practical continuity checks for a fresh session + +The session is recoverable if it can, from the repository alone, answer: + +- Which task is active and where to continue? +- What phase is current (`NOT_STARTED` / `IN_PROGRESS` / `COMPLETED`)? +- What blockers and assumptions are known? +- What evidence was last verified and where is it stored? +- What exact next action is safe to perform next? + +Any ambiguous active state should be treated as blocked and converted into an explicit checkpoint update rather than implicit inference. + +## 4) Deployment continuity rule + +- Bootstrap config should remain minimal and task-locating. +- Live canonical configuration belongs to canonical ownership and project artifacts, not ambient shell session state. +- Missing runtime assumptions must fail early during startup checks, not defer silently to manual behavior. + +## 5) Evidence expectations for this task family (DEV-000074) + +- `docs/PROJECT_STATUS.md` checkpoint updated for DEV-000074. +- `AGENTS.md` contains the startup and checkpoint governance. +- `dev/ACTIVE_TASK.json` points to the active DEV-000074 packet. +- Evidence artifact file or command output captured for cold-start reconstruction validation. + diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 5a50ab6..b6cf838 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,6 +1,20 @@ # Assistant project status -Audit date: 2026-08-17. Active implementation: DEV-000072 revision 1. +Audit date: 2026-08-18. Active implementation: DEV-000074. + +## DEV-000074 checkpoint + +- `DEV_000074_STATUS = IN_PROGRESS` +- `TASK_SCOPE = governance/cold-start continuity` +- `CURRENT_PHASE = CONTEXT_AND_CHECKPOINT_CONSOLIDATION` +- `COMPLETED = AGENTS.md startup/continuity sequence clarified; Cold start reconstruction guide added; task packet created; active task pointer updated` +- `IN_PROGRESS = architecture/diff checks and evidence verification for cold start reconstruction` +- `NOT_STARTED = product behavior, runtime configuration, or architecture migration changes` +- `BLOCKERS = none` +- `IMPORTANT_FINDINGS = chat-only state is insufficient for reconstruction; repository artifacts are now explicitly documented` +- `EVIDENCE_OBTAINED = AGENTS.md, docs/COLD_START_AND_DURABLE_CHECKPOINT.md, dev/ACTIVE_TASK.json, dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json, check output` +- `LAST_VERIFIED_COMMIT = fd59b93463bea80459375ecb28864c03ec3efc42` +- `NEXT_ACTION = run required checks for DEV-000074 and report completion` ## DEV-000072 checkpoint diff --git a/docs/evidence/dev-000074-cold-start-reconstruction.md b/docs/evidence/dev-000074-cold-start-reconstruction.md new file mode 100644 index 0000000..e1ac409 --- /dev/null +++ b/docs/evidence/dev-000074-cold-start-reconstruction.md @@ -0,0 +1,153 @@ +# DEV-000074 cold-start reconstruction proof +Date: 2026-08-18T00:19:35.0288130+03:00 + +1) Git context +Branch: codex/dev-000072-semantic-deferral-boundary-v1 +HEAD: fd59b93463bea80459375ecb28864c03ec3efc42 +origin/main: 11a6a23f6e4f44dd88265a04846419a27f54df98 +MergeBase: ce666bbc43842d339e760957e3c59c490ae1c18a +Status: + M AGENTS.md + M dev/ACTIVE_TASK.json + M docs/PROJECT_STATUS.md +?? dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json +?? docs/COLD_START_AND_DURABLE_CHECKPOINT.md +?? docs/evidence/dev-000074-cold-start-reconstruction.md + +2) Active task pointer +{ + "task_file": "dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "task_id": "DEV-000074", + "task_revision": 1 +} + + +3) Active task file exists +True + +4) DEV-000074 packet +{ + "task_id": "DEV-000074", + "task_revision": 1, + "architecture_revision": "arch-generation-1", + "base_repo_revision": "fd59b93463bea80459375ecb28864c03ec3efc42", + "risk_tier": "E", + "intent": "Consolidate Codex development memory and cold-start continuity so a fresh session can reconstruct active milestone, boundaries, tests, and next action from repository artifacts only. Do not change Domovoy product behavior; do not change deployment runtime configuration.", + "requirement_ids": [ + "DEV-000061 governance continuity", + "FOUNDATION_EXIT_AUDIT checkpoint continuity", + "Cold-start reconstruction from repository only", + "No product behavior regression", + "Durable continuation fields" + ], + "allowed_change_scope": { + "modules": [], + "paths": [ + "AGENTS.md", + "docs/PROJECT_STATUS.md", + "docs/COLD_START_AND_DURABLE_CHECKPOINT.md", + "docs/evidence/dev-000074-cold-start-reconstruction.md", + "dev/ACTIVE_TASK.json", + "dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json" + ] + }, + "forbidden_change_scope": { + "paths": [ + "architecture/ARCHITECTURE_CONSTITUTION.md", + "architecture/architecture-registry.yaml", + "architecture/architecture-registry.json", + "architecture/adrs/**", + "security/**", + "modules/**", + "contracts/**", + "adapters/**", + "cmd/**", + "deploy/**", + ".gitea/**", + "ci/**" + ] + }, + "allowed_architecture_delta": { + "new_cross_module_dependencies": 0, + "new_canonical_owners": 0, + "new_privileges": 0, + "new_third_party_dependencies": 0, + "new_provider_adapters": 0, + "new_database_owner_roles": 0 + }, + "contracts": { + "consume": [], + "may_change": [] + }, + "semantic_owner": "governance", + "canonical_state": [ + "AGENTS.md contains the durable cold-start startup sequence and checkpoint rules.", + "Checkpoint continuity is preserved in docs/PROJECT_STATUS plus reconstructed durable checkpoint fields." + ], + "state_transitions": [ + "Fresh session -> read required artifacts -> reconstruct active task and phase", + "Checkpoint update -> clear/record blockers -> define next action", + "Preflight and checks -> produce final continuity status and evidence" + ], + "side_effects_and_privileges": [ + "No direct external mutation", + "No runtime/runtime-host configuration changes", + "No production actions" + ], + "persistence_and_migrations": [ + "No database migration", + "No schema or privilege change", + "No canonical ownership change" + ], + "failure_retry_restart": [ + "If required startup artifacts are missing, return BLOCKED_BY_MISSING_CAPABILITY and update checkpoint.", + "If checkpoint and active task disagree, BLOCKED_BY_SPEC_GAP and require a corrective checkpoint update.", + "Execution-window exhaustion is continuation state, not failure." + ], + "assumptions": [ + "Foundation architecture and ADR set is already accepted.", + "No production behavior change is authorized in this milestone." + ], + "acceptance_scenarios": [ + "Fresh session reconstructs active DEV, phase, blockers, and next action from artifacts alone.", + "ACTIVE_TASK points to DEV-000074 task packet after switching.", + "AGENTS cold-start checklist remains practical and non-duplicative.", + "Docs checkpoint explicitly records durable status with explicit evidence references.", + "Architecture/diff checks pass.", + "No changed files outside governance/documentation scope." + ], + "required_tests": [ + "go test ./...", + "go vet ./...", + "go run ./cmd/devctl preflight -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "go run ./cmd/devctl check-architecture", + "go run ./cmd/devctl check-diff -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json", + "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json" + ], + "terminal_gap_states": [ + "BLOCKED_BY_SPEC_GAP", + "BLOCKED_BY_ARCHITECTURE_GAP", + "BLOCKED_BY_MISSING_CAPABILITY", + "BLOCKED_BY_CONFLICT", + "REQUIRES_MIGRATION_DECISION" + ] +} + + +5) Required startup files +AGENTS.md => True +architecture/ARCHITECTURE_CONSTITUTION.md => True +architecture/CORE_SEMANTIC_MODEL_V1.md => True +architecture/architecture-registry.yaml => True +architecture/architecture-registry.json => True +development/CODEX_DEVELOPMENT_CONTRACT.md => True +docs/PROJECT_STATUS.md => True +docs/COLD_START_AND_DURABLE_CHECKPOINT.md => True + +6) Required checks executed +go test ./... => PASS +go vet ./... => PASS +go run ./cmd/devctl preflight -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json => PASS +go run ./cmd/devctl check-architecture => PASS +go run ./cmd/devctl check-diff -task dev/tasks/DEV-000074-durable-codex-project-memory-agents-consolidation.json => PASS +go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json => PASS