# Universal Assistant — Foundation Freeze Pack V1

Версия: 1.0  
Дата фиксации: 16 августа 2026  
Основание: Architecture Specification V2 + adversarial review + Codex-oriented development review  
Статус: **IMPLEMENTATION BASELINE CANDIDATE**

# 1. ARCHITECTURE_CONSTITUTION.md

## 1.1 Назначение

Этот документ — краткий набор законов репозитория и production-архитектуры. Он выше обычных task packets, примеров и локальных README. Codex не является архитектурным authority: он реализует только то, на что выдана task authority.

## 1.2 Иерархия архитектурной власти

1. Architecture Constitution.
2. Accepted ADR / Foundation Decision.
3. Machine-readable Architecture Registry.
4. Versioned semantic contracts and state machines.
5. Module architecture specification.
6. Codex Task Packet.
7. Implementation and examples.

Если нижний уровень противоречит верхнему, нижний считается ошибочным. Существующий код является evidence of implementation, но не authority to redefine architecture.

## 1.3 Неприкосновенные инварианты V1

1. LLM/model/provider не является Assistant.
2. Capability не означает Authority.
3. Observation, Claim, Belief, Prediction, Action и Outcome — разные семантические классы.
4. Model output никогда напрямую не мутирует canonical semantic state и не выполняет external mutation.
5. Любая реальная мутация проходит Proposal → semantic owner validation → Authority/Integrity checks → Commit → Executor → Outcome/Verification.
6. Любая executable activity имеет live justification path к действующей Goal, Commitment, Responsibility или Policy.
7. Отмена/суперсессия justification должна распространяться до зависимых работ перед следующим commit.
8. Canonical owner — один на конкретный mutable semantic state в конкретной semantic generation.
9. Другие модули не пишут canonical storage владельца напрямую.
10. Cross-owner SQL writes, cross-owner FK и скрытая cross-owner trigger logic запрещены по умолчанию.
11. Derived projections/caches/indexes не являются source of truth и должны быть rebuildable либо явно classified otherwise.
12. Temporal/NATS/Redis/vector index/model memory не являются единственным местом хранения commitments, authority, semantic history или future obligations.
13. Durable future obligations живут в canonical prospective state независимо от workflow/scheduler engine.
14. External side effect должен быть idempotent/reconcilable; timeout не равен failure; UNKNOWN_OUTCOME — first-class state.
15. No correctness property may depend on a shared in-process lock across bounded modules.
16. Semantic topology, process topology, storage topology и model topology независимы и меняются отдельно.
17. Co-location — deployment optimization, не архитектурная привилегия.
18. Major bounded contracts должны быть serializable и не зависеть от Go pointers, shared memory, global variables или ambient process state.
19. Core/domain не импортирует PostgreSQL/NATS/Temporal/MCP/model-provider packages.
20. Никакого giant `common/shared` domain package; technical shared mechanisms допускаются только в `platform` и не владеют domain semantics.
21. Semantic duplication предпочтительнее ложной абстракции.
22. Event-driven взаимодействие используется ради temporal decoupling/history, а не потому, что два модуля разные.
23. Public query не должен скрыто изменять canonical state.
24. Durable background responsibility не реализуется unmanaged goroutine/timer.
25. `context.Context` не переносит скрытый user/scope/authority/task state; это явные typed fields.
26. Unknown/Conflict/NotApplicable/NotObserved не схлопываются в nil/false/default.
27. Type system, package visibility, DB ACL и CI должны делать критические ошибки невозможными там, где это возможно.
28. Architecture guardrails themselves are protected and cannot validate their own weakening alone.
29. Codex ordinary feature task не меняет Constitution, Architecture Registry, public semantic topology, guardrails или canonical ownership без отдельного approved change.
30. Codex может завершить задачу typed gap (`BLOCKED_BY_SPEC_GAP`, `BLOCKED_BY_ARCHITECTURE_GAP`) вместо архитектурного обхода.
31. Every persistent thing has lifecycle, owner/justification, stop/retirement path and recovery semantics appropriate to criticality.
32. Historical meaning is not rewritten by current interpretation; corrections/supersessions are appended/versioned.
33. Newer/stronger model never automatically receives broader authority.
34. More intelligence, more code, more services or more automations are not goals themselves.
35. KEEP/WAIT/DO_NOTHING are valid decisions.
36. The system must remain recoverable, exportable and replaceable.

## 1.4 Codex-specific hard prohibitions

- No direct cross-module DB access “temporarily”.
- No cross-schema JOIN as application dependency between canonical owners.
- No direct provider/model call outside Cognitive Gateway/adapters.
- No external mutation outside Commit/Executor path.
- No generic `SaveEntity(any)`, `Invoke(any)`, global Service Locator or God Context.
- No semantic side effects in Go package `init()`.
- No semantic durable timers using `time.After`/sleep in request process.
- No production semantic behavior hidden only in middleware, SQL trigger or YAML DSL.
- No silent retry of ambiguous external mutation.
- No weakening of architecture/security tests inside unrelated feature task.
- No new third-party dependency, canonical table, integration contract or privileged secret access without declared change classification.

## 1.5 Core change rule

Change the lowest layer that eliminates the causal class of the problem. Escalate only when necessary:

`data/config → local implementation → skill/strategy → module contract → ownership/schema → architecture → constitutional invariant`.


---

# 2. DECISION_CONSOLIDATION_V1.md

## 2.1 Purpose

This inventory separates accepted decisions from explored ideas. Statuses are normative:

- **ACCEPTED_V1** — implementation may rely on it now.
- **EXTENSION_POINT_V1** — foundation must not block it; no full implementation required.
- **LATER** — explicitly excluded from current implementation scope.
- **RESEARCH** — unresolved; Codex must not choose a permanent answer silently.
- **REJECTED_V1** — do not implement this approach in V1.

## 2.2 Accepted foundation decisions

| ID | Decision | Status | Implementation consequence |
|---|---|---|---|
| FD-001 | Assistant ≠ LLM/model/provider/process | ACCEPTED_V1 | Cognitive providers are replaceable capabilities. |
| FD-002 | Extractable Modular Architecture | ACCEPTED_V1 | Deploy together when useful, design bounded components separately. |
| FD-003 | One PostgreSQL cluster may host V1, but canonical owners use separate schemas/roles | ACCEPTED_V1 | DB ACL physically prevents cross-owner writes. |
| FD-004 | Cross-owner FK/trigger business logic forbidden by default | ACCEPTED_V1 | Relations use semantic IDs/contracts/projections. |
| FD-005 | NATS/Temporal/Redis are implementation mechanisms, not semantic sources of truth | ACCEPTED_V1 | Canonical event/prospective state survives their loss. |
| FD-006 | Major cross-boundary contracts are remote-capable | ACCEPTED_V1 | In-process and remote adapters satisfy same contract tests. |
| FD-007 | No mandatory microservice-per-noun | ACCEPTED_V1 | Semantic modules and deployment runtimes are independent mappings. |
| FD-008 | Commit/Executor is an early physical isolation boundary | ACCEPTED_V1 | External credentials and mutation authority are not globally available. |
| FD-009 | Model output produces candidates/proposals, never direct canonical mutation | ACCEPTED_V1 | Typed semantic validation and commit gates. |
| FD-010 | Canonical event/outbox pattern for cross-owner durable reactions | ACCEPTED_V1 | Owner-local ACID + outbox; no distributed ACID assumption. |
| FD-011 | Prospective Memory canonicalized outside Temporal | ACCEPTED_V1 | Reminder/wake/commitment state rebuilds after workflow-engine loss. |
| FD-012 | Identity, Principal, Scope and Authority are separate concepts | ACCEPTED_V1 | Strong typed IDs and explicit command envelopes. |
| FD-013 | Goal/Task/Action/Outcome are distinct | ACCEPTED_V1 | Task completion does not imply goal/outcome success. |
| FD-014 | Situation binds request to project/workspace/environment via runtime context, not keywords | ACCEPTED_V1 | Focus Isolation Suite is foundational acceptance test. |
| FD-015 | Unknown and conflict states preserved | ACCEPTED_V1 | No premature boolean/default collapse. |
| FD-016 | Bitemporal-capable history model | ACCEPTED_V1 | Separate event/observed/valid/recorded semantics where relevant. |
| FD-017 | Canonical history append/supersede rather than retroactive semantic rewrite | ACCEPTED_V1 | Historical replay can reconstruct what was known then. |
| FD-018 | Development through Codex requires Development Commit Gate | ACCEPTED_V1 | Task authority + CI/ACL/architecture checks precede merge. |
| FD-019 | Architecture is executable | ACCEPTED_V1 | Critical rules need compiler/linter/ACL/test/observability enforcement. |
| FD-020 | V1 uses explicit boring typed mechanisms over meta-frameworks/DSLs | ACCEPTED_V1 | No generic entity engine/universal workflow DSL. |
| FD-021 | Contract/state ownership precedes DDL/protobuf | ACCEPTED_V1 | Schema is derived from semantic contracts. |
| FD-022 | Walking Skeleton before broad subsystem implementation | ACCEPTED_V1 | Foundation validated vertically, not through stub zoo. |
| FD-023 | Stronger future model is candidate, not automatic replacement | ACCEPTED_V1 | Eval/shadow/canary/promotion lifecycle. |
| FD-024 | Architecture boundaries are hypotheses and may split/merge | ACCEPTED_V1 | Stable IDs/lineage; topology migration supported. |
| FD-025 | Critical deterministic invariants are not delegated to free-form LLM judgment | ACCEPTED_V1 | Fuzzy cognition proposes; deterministic gates enforce. |

## 2.3 Extension points that must be preserved now

| ID | Topic | Status | V1 requirement |
|---|---|---|---|
| EP-001 | Portfolio/Trajectory engines | EXTENSION_POINT_V1 | Core goal/project/event model must permit later orchestration. |
| EP-002 | Responsibilities/Risks/Opportunities/ControlLoops | EXTENSION_POINT_V1 | Semantic namespaces/lifecycles extensible; no full engines required. |
| EP-003 | Self-development/self-migration | EXTENSION_POINT_V1 | Architecture/change provenance and replacement paths exist; autonomous self-editing absent. |
| EP-004 | Collective/global learning | EXTENSION_POINT_V1 | Knowledge provenance/scope prevents unsafe future promotion. |
| EP-005 | Multi-user/organization federation | EXTENSION_POINT_V1 | Actor/Principal/Scope not hardcoded to single user. |
| EP-006 | Robotics/edge realtime control | EXTENSION_POINT_V1 | Capability/authority model supports out-of-process bounded controllers. |
| EP-007 | Alternate coding agents | EXTENSION_POINT_V1 | Codex Task Packet provider-neutral; Codex adapter first. |
| EP-008 | Semantic generation migration | EXTENSION_POINT_V1 | Version/schema IDs and migration framework exist; no universal ontology engine. |

## 2.4 Explicit V1 non-goals

The following are **LATER or RESEARCH**, not implementation requirements for Foundation V1:

- autonomous production self-modification;
- autonomous installation of arbitrary plugins/components;
- global collective learning between unrelated users;
- Kubernetes requirement;
- custom consensus protocol;
- custom database or event-bus implementation;
- full robotics stack;
- universal ontology/DSL engine;
- one service per semantic noun;
- complete multi-tenant enterprise federation;
- training custom foundation models as part of V1;
- perfect global causal graph;
- general autonomous portfolio optimization of human life;
- fully autonomous Codex development swarm.

## 2.5 Rejected V1 approaches

- REJECTED: “Start as free modular monolith and split later.”
- REJECTED: giant shared domain model/package.
- REJECTED: cross-module joins because “same DB for now”.
- REJECTED: event-sourcing everything by default.
- REJECTED: microservices for every primitive.
- REJECTED: direct LLM→tool→world mutation path.
- REJECTED: Temporal workflow as canonical future obligation.
- REJECTED: vector DB/Redis/model memory as canonical knowledge.
- REJECTED: generic `entity(type,payload jsonb)` as primary Core model.
- REJECTED: implicit global utility score for all goals.
- REJECTED: relying on Codex remembering architecture from previous sessions.


---

# 3. CORE_SEMANTIC_MODEL_V1.md

## 3.1 Scope

This is a V1 semantic freeze, not an eternal ontology. It defines the minimum durable concepts required to build the walking skeleton and preserve future migration freedom.

## 3.2 Canonical Core V1 concepts

### Identity
Stable semantic identity independent of current name, locator, account, process or key. Supports identifier history and future merge/split corrections.

### Actor
Entity capable of requests/actions/representation. Actor is not automatically a Principal.

### Principal
The person/organization/accounting/legal/operational interest on whose behalf an action is performed. Same human may act for multiple principals.

### Scope
Boundary for data, authority, project/context and permissible propagation.

### AuthorityGrant / AuthorityContext
Evidence that an Actor may perform a class of actions for a Principal within Scope and validity conditions. Capability never implies grant.

### Situation
Time-bounded interpretation of “what is happening now”: actor, interface/session, focus, project/workspace/environment bindings, active task, relevant resources, confidence/provenance. Situation is derived and expires/revalidates.

### Observation
Something obtained from a source/sensor/tool/user report. Carries provenance, observed time, coverage and source semantics.

### Claim
A proposition asserted by a source or derived system. It is not automatically fact.

### Belief/Assessment
Current system interpretation supported by evidence; versioned/revisable and scoped.

### Intent
Current request/desired change inferred from interaction; can be revised/superseded. Intent is not automatically long-term preference.

### Goal
Desired world/state transition or outcome with lifecycle and lineage. Goal may be refined/superseded; method is not identical to goal.

### Task
Durable unit of work that must survive session/process, coordinate actors, or carry lifecycle significance. Ephemeral reasoning steps are not Tasks.

### Decision
Selection/commitment among alternatives with rationale/evidence refs where consequence warrants. Decision can have validity/revisit conditions.

### ActionProposal
Structured candidate to change canonical state, communicate, allocate resources or mutate external world. Proposal has no execution authority by itself.

### AuthorizedAction
Proposal that passed owner validation, current authority, revision/target/integrity checks and received commit identity.

### ActionAttempt
Concrete execution attempt of an AuthorizedAction. Multiple attempts may serve one ActionIntent; attempt is not outcome.

### Outcome
Observed/verifiable result attributable with stated confidence. Supports UNKNOWN/partial/provisional maturity.

### Commitment
A future obligation/expectation created by promise/agreement/explicit user request/policy. Must have owner/beneficiary, fulfilment or renegotiation path and prospective continuity.

### ProspectiveItem
Canonical future-relevance object used by Continuity for reminder/wake/review/expected transition. V1 may implement only reminder/wake subset; it remains independent of Temporal.

### Event
Meaningful semantic transition or occurrence. Event is not a log line and not every low-level tool callback becomes Event.

### Artifact
Durable content/resource with identity, content/schema metadata, provenance and scope. Payload may live outside PostgreSQL.

### Capability
Declared/tested ability to observe, reason, communicate or act, with contracts, limits, provenance, health and allowed-use metadata. Capability availability ≠ authority.

### Revision
Optimistic semantic version/precondition for mutable canonical objects and contracts.

### Provenance
Lineage linking observations, claims, derived states, actions and artifacts to sources/derivations without treating copies as independent evidence.

## 3.3 Concepts intentionally NOT Core primitives in V1

These remain extension/derived concepts until evidence requires promotion: `Thread`, `Journey`, `Program`, `Trajectory`, `Portfolio`, `Responsibility`, `Risk`, `Opportunity`, `Monitor`, `ControlLoop`, `Routine`, `Theory`, `Frontier`. Foundation must permit them later but Codex must not materialize separate Core tables/services merely because they were discussed.

## 3.4 Required semantic distinctions

`Actor ≠ Principal`  
`Identity ≠ Identifier ≠ Locator`  
`Situation ≠ RequestContext ≠ ModelContext`  
`Observation ≠ Claim ≠ Belief`  
`Intent ≠ Goal ≠ Task`  
`Task ≠ ActionProposal ≠ AuthorizedAction ≠ ActionAttempt ≠ Outcome`  
`Commitment ≠ Reminder delivery`  
`Capability ≠ Authority`  
`Event ≠ Integration message ≠ Log`  
`Canonical state ≠ Projection ≠ Cache`  
`Prediction ≠ Expected-by-process ≠ Required-by-commitment`.

## 3.5 Required state semantics

### Goal lifecycle (minimum)
`ACTIVE | WAITING | DORMANT | SATISFIED | SUPERSEDED | ABANDONED`

Transitions must preserve reason and lineage. `ABANDONED` does not mean failure; `SUPERSEDED` must point to successor when known.

### Task lifecycle (minimum)
`PENDING | ACTIVE | WAITING | COMPLETED | CANCELLED | FAILED`

Task has `revision`, `justification_ref`, optional `wake_condition_ref`, owner and completion evidence. `WAITING` must say what it waits for or be explicitly dormant at higher level.

### Action lifecycle
`PROPOSED → VALIDATED → AUTHORIZED/REJECTED → EXECUTING → SUCCEEDED | FAILED | UNKNOWN_OUTCOME | COMPENSATED`.

Retry preserves ActionIntent identity and creates a new attempt identity. `UNKNOWN_OUTCOME` blocks blind retry when duplicate effect is possible.

### Commitment lifecycle
`ACTIVE | WAITING | AT_RISK | FULFILLED | RENEGOTIATED | REVOKED | EXPIRED`.

Future promise is not fulfilled by notification delivery alone unless the promise itself was only to notify.

### Prospective item lifecycle
`REGISTERED | ARMED | TRIGGERED | REVALIDATING | DELIVERED/STARTED | SATISFIED | SUPPRESSED | EXPIRED`.

Trigger firing does not bypass relevance/authority revalidation.

## 3.6 Temporal model

Foundation must support distinguishing, where applicable:

- event/occurrence time;
- observed time;
- recorded time;
- validity interval;
- local-time intention vs absolute instant;
- relative schedule relation (`after Event X + duration`) vs prematurely flattened timestamp.

Do not put four timestamps on every row blindly. Use common temporal value objects/contracts only where semantics require them.

## 3.7 Strong identifiers

Go Core should use distinct types for at least: `IdentityID`, `ActorID`, `PrincipalID`, `ScopeID`, `SituationID`, `GoalID`, `TaskID`, `CommitmentID`, `ActionIntentID`, `ActionAttemptID`, `ArtifactID`, `CapabilityID`, plus revision types. They serialize to language-neutral primitives.

## 3.8 Ownership baseline

| Semantic area | Canonical owner V1 | Notes |
|---|---|---|
| Identity/Actor/Principal bindings | Identity module | Other modules reference IDs/projections only. |
| Scope/Authority grants | Authority module | Commit queries current validation; no hidden default authority. |
| Situation/focus bindings | Situation module | Derived/ephemeral portions may use cache, but durable bindings/provenance explicitly classified. |
| Goal/Task/Decision | Work module | Can later split; V1 owner chosen to preserve local consistency. |
| Commitment/Prospective items | Continuity module | Temporal is execution engine adapter, not owner. |
| Observations/Claims/Beliefs/Provenance | Epistemics module | Search/vector indexes derived. |
| Action commit state | Commit module | External executor isolated. |
| Artifact metadata/lineage | Artifact module or platform-owned artifact service | Payload storage replaceable. |
| Capability registry/bindings | Capability module | Provider-specific adapters outside semantic owner. |

## 3.9 Consistency baseline

- Authority validation and Action authorization: strong owner-local consistency + revision preconditions.
- Task state transitions: owner-local optimistic revision/CAS.
- Cross-owner projections: eventual/rebuildable unless an explicit use case requires stronger semantics.
- UI aggregate views: derived projections; no cross-owner canonical joins.
- Integration reactions: owner-local commit + transactional outbox; consumers idempotent.
- No global total event order requirement; causal/aggregate ordering only where needed.


---

# 4. architecture-registry.yaml

Below is the normative starter registry. It is intentionally small. Tooling may extend the schema, but new relation types must have an enforcement/use case.

```yaml
registry_version: 1
semantic_generation: 1
architecture_generation: 1

modules:
  identity:
    id: mod.identity
    owns: [Identity, Actor, PrincipalBinding]
    database_schema: identity
    boundary_class: remote_capable
    may_depend_on: [platform.ids, platform.events]
    forbidden: [adapters.models, adapters.temporal]

  authority:
    id: mod.authority
    owns: [Scope, AuthorityGrant, AuthorityValidation]
    database_schema: authority
    boundary_class: remote_capable
    may_depend_on: [contracts.identity, platform.ids, platform.events]

  situation:
    id: mod.situation
    owns: [Situation, FocusBinding]
    database_schema: situation
    boundary_class: remote_capable
    may_depend_on: [contracts.identity, contracts.work, contracts.capability]

  work:
    id: mod.work
    owns: [Goal, Task, Decision]
    database_schema: work
    boundary_class: remote_capable
    may_depend_on: [contracts.identity, contracts.authority, platform.events]

  epistemics:
    id: mod.epistemics
    owns: [Observation, Claim, Belief, Provenance]
    database_schema: epistemics
    boundary_class: remote_capable
    may_depend_on: [contracts.identity, contracts.artifact, platform.events]

  continuity:
    id: mod.continuity
    owns: [Commitment, ProspectiveItem]
    database_schema: continuity
    boundary_class: remote_capable
    may_depend_on: [contracts.work, contracts.identity, contracts.authority, platform.events]

  capability:
    id: mod.capability
    owns: [Capability, CapabilityBinding, CapabilityHealth]
    database_schema: capability
    boundary_class: remote_capable
    may_depend_on: [contracts.identity, contracts.authority, contracts.artifact]

  commit:
    id: mod.commit
    owns: [ActionProposalRecord, AuthorizedAction, ActionAttemptRecord]
    database_schema: commit
    boundary_class: remote_capable
    may_depend_on: [contracts.authority, contracts.capability, contracts.work, platform.events]
    privileged: true

  artifact:
    id: mod.artifact
    owns: [ArtifactMetadata, ArtifactLineage]
    database_schema: artifact
    boundary_class: remote_capable
    may_depend_on: [contracts.identity]

platform:
  allowed_packages:
    - platform.ids
    - platform.clock
    - platform.outbox
    - platform.inbox
    - platform.telemetry
    - platform.errors
  rule: "platform owns mechanisms, never domain meaning"

runtime_topology_v1:
  core_runtime:
    modules: [identity, situation, work, epistemics, capability, artifact]
  continuity_runtime:
    modules: [continuity]
  commit_runtime:
    modules: [authority, commit]
    isolation_reason: [secrets, external_mutation_authority, failure_isolation]
  cognitive_workers:
    modules: []
    role: "replaceable cognition/context compilation workers; no canonical ownership"

storage_topology_v1:
  postgres_cluster: assistant_primary
  schemas:
    identity: identity_role
    authority: authority_role
    situation: situation_role
    work: work_role
    epistemics: epistemics_role
    continuity: continuity_role
    capability: capability_role
    commit: commit_role
    artifact: artifact_role
  cross_owner_fk: forbidden_by_default
  cross_owner_write: forbidden
  cross_owner_application_join: forbidden

invariants:
  - id: INV-AUTH-001
    property: "No external mutation without current valid authority and target/revision checks"
    class: HARD
    enforcement: [commit_runtime, property_tests, secret_acl]
  - id: INV-OWN-001
    property: "Only semantic owner writes canonical state"
    class: HARD
    enforcement: [db_acl, architecture_linter]
  - id: INV-CONT-001
    property: "Future obligations survive workflow engine loss"
    class: HARD
    enforcement: [canonical_prospective_store, recovery_test]
  - id: INV-TOPO-001
    property: "Major bounded contracts preserve semantics across inproc and remote topology"
    class: HARD
    enforcement: [topology_equivalence_tests]
  - id: INV-EPI-001
    property: "Model output cannot directly become canonical fact/action"
    class: HARD
    enforcement: [package_boundaries, commit_apis, semantic_validation_tests]
  - id: INV-PROJ-001
    property: "Projection eventually converges from canonical state"
    class: CONVERGENCE
    enforcement: [projection_rebuild_tests, lag_metrics]

protected_paths:
  - architecture/ARCHITECTURE_CONSTITUTION.md
  - architecture/architecture-registry.yaml
  - architecture/adrs/**
  - ci/architecture/**
  - security/**

default_feature_task_authority:
  may_write: ["declared module paths", "module-owned tests"]
  may_not_change:
    - canonical_ownership
    - public_cross_module_contracts
    - protected_paths
    - third_party_dependencies
    - database_owner_roles
    - privileged_capabilities
```

## 4.1 Registry enforcement required before large Codex implementation

Minimum deterministic checks:

1. Go import graph against `may_depend_on`/forbidden edges.
2. No `/modules/*/domain` imports from adapters/runtime/provider packages.
3. Migration scanner rejects cross-owner writes/FKs/triggers/views unless explicit approved exception.
4. PostgreSQL role tests prove owner isolation.
5. Diff-scope check against Codex Task Packet.
6. Protected-path rule.
7. Public contract change detection.
8. Required CI guardrail health: missing checker result is failure, not pass.


---

# 5. CODEX_DEVELOPMENT_CONTRACT.md

## 5.1 Role

Codex is an implementation capability. It can inspect, design locally, code, test and propose findings. It is **not** architectural authority and does not receive production authority merely because it can edit source.

## 5.2 Task Packet schema

Every non-trivial Codex implementation task must resolve to a packet similar to:

```yaml
task_id: DEV-000123
task_revision: 3
architecture_revision: <git-sha-or-registry-revision>
base_repo_revision: <git-sha>
risk_tier: B
intent: "..."
requirement_ids: [REQ-...]
allowed_change_scope:
  modules: [work]
  paths: [modules/work/**, contracts/work/**]
forbidden_change_scope:
  paths: [architecture/**, security/**, modules/identity/**]
allowed_architecture_delta:
  new_cross_module_dependencies: 0
  new_canonical_owners: 0
  new_privileges: 0
contracts:
  consume: [contracts.identity@v1, contracts.authority@v1]
  may_change: []
semantic_owner: work
assumptions: []
acceptance_scenarios: [SCN-...]
required_tests: [unit, contract, architecture]
terminal_gap_states:
  - BLOCKED_BY_SPEC_GAP
  - BLOCKED_BY_ARCHITECTURE_GAP
  - BLOCKED_BY_MISSING_CAPABILITY
```

## 5.3 Risk tiers

- **Tier A — module-local:** no public contract/schema ownership/privilege changes. Fast path.
- **Tier B — module contract/persistence local:** owner-local schema or stable port changes. Migration/contract tests.
- **Tier C — cross-module:** integration contracts/events/topology interactions. Independent architecture review.
- **Tier D — authority/canonical migration/external side effects:** adversarial/property/recovery tests and stricter promotion.
- **Tier E — Core/guardrails/constitutional:** proposal first; changed verifier cannot self-certify.

## 5.4 Codex preflight for Tier B+

Before write, produce structured implementation plan containing:

- modules/files expected to change;
- semantic owner(s);
- contracts consumed/changed;
- canonical state and state-machine transitions affected;
- side effects/privileges;
- persistence/migrations/events;
- failure/retry/restart semantics;
- tests to prove invariants.

Plan is machine-checked against Task Packet. Unexpected architecture delta becomes finding/gap.

## 5.5 Allowed local freedom

Inside an owned module Codex may choose ordinary data structures, algorithms, file decomposition and local refactoring, provided public contracts/invariants/task scope remain intact. Architecture defines constraints, not every function.

## 5.6 Mandatory Codex completion report

- changed files/modules;
- contracts/schemas/events/dependencies/privileges touched;
- tests actually executed (CI is authoritative evidence);
- assumptions made;
- known limitations;
- unrelated findings not changed;
- any specification/architecture gaps.

## 5.7 Development Commit Gate

Candidate patch → deterministic build/tests → architecture sentinel → DB/migration checks → contract checks → risk-specific review → exact-artifact promotion/merge.

Ordinary Codex tasks never write protected main directly. Promotion moves the evaluated artifact/commit, not a rebuilt unknown variant.

## 5.8 Architecture Sentinel responsibilities

Deterministically compare declared vs observed architecture:

- import/dependency graph;
- DB writes/FKs/views/triggers;
- event publishers/subscribers;
- protected path and diff scope;
- third-party dependency diff;
- public contract diff;
- privileged secret/capability access where enforceable;
- guardrail execution health.

AI reviewer handles semantic smells that cannot be mechanically proven: God Ports, ownership leakage, false abstraction, orchestration absorbing domain semantics, hidden co-location assumptions, unsafe retry reasoning.

## 5.9 Architecture exceptions

No `nolint`/architecture ignore without registered exception ID containing reason, scope, expiry/removal condition. New debt cannot be introduced silently. Existing baseline debt can be ratcheted down.

## 5.10 Codex failure is valid

Codex is explicitly allowed to return a typed gap rather than “make it work somehow”. A gap becomes architecture/spec/research task and may revise the original task packet. This is preferred to an unapproved shortcut.

## 5.11 Cold Agent requirement

At major milestones, a fresh Codex session with no conversational history must be able to explain module ownership/boundaries and implement a bounded task using canonical repo artifacts only. Critical architecture cannot live only in chat history.


---

# 6. WALKING_SKELETON_SPEC.md

## 6.1 Goal

Prove the Foundation through a small set of end-to-end semantic properties before broad implementation. Do not build all future modules/stubs first.

## 6.2 Skeleton topology

Initial process topology:

```text
Client/Test Harness
      |
Core Runtime
  - Identity
  - Situation
  - Work
  - Epistemics (minimal)
  - Capability registry (minimal)
      |
      +---- Cognitive Worker Adapter (deterministic fake first, real model later)
      |
      +---- Continuity Runtime ---- Temporal adapter (optional/replaceable)
      |
      +---- Commit Runtime (separate process, isolated credentials)
                    |
                 Test Executor
```

One PostgreSQL cluster, separate owner schemas/roles. NATS may be used for integration events once owner-local outbox exists; skeleton must also prove semantics do not live only in NATS.

## 6.3 Scenario WS-001 — Focus Isolation / wrong-project prevention

**Given** one Actor has two simultaneously active Codex/workspace situations bound to Project/Goal contexts A and B. Both domains contain an identically named concept such as `temperature`.

**When** the identical user phrase is sent through each session without naming the project.

**Then** Situation resolution binds each request to its own session/workspace/project context using runtime bindings/provenance; no keyword shortcut is allowed; canonical writes carry target/revision/scope and cannot affect the other context.

Required failure cases:
- stale focus binding;
- two worktrees of same repository;
- ambiguous target → typed ambiguity, no mutation;
- Task revision changed between reasoning and commit → commit rejected/re-evaluated.

Acceptance property: **wrong-project mutation is mechanically prevented even if cognition proposes the wrong target**.

## 6.4 Scenario WS-002 — Durable prospective memory independent of Temporal

**Given** user creates a future reminder/commitment with semantic context and fulfilment condition.

**When** canonical Continuity transaction commits, process restarts, Temporal state is deleted/unavailable, then workflow infrastructure is rebuilt.

**Then** obligation remains in PostgreSQL canonical prospective state, is reconstructed, does not duplicate occurrence, revalidates relevance before delivery, and can distinguish `DELIVERED` from underlying `FULFILLED`.

Failure cases:
- system offline past trigger;
- 100 duplicate trigger messages;
- goal superseded before trigger;
- delivery channel unavailable;
- recurrence missed during outage.

Acceptance property: **loss of workflow engine does not lose or blindly replay future obligations**.

## 6.5 Scenario WS-003 — Safe Action Commit and unknown outcome

**Given** cognition produces a structured external mutation proposal.

**When** Commit Runtime receives it.

**Then** it validates current Authority, Scope, Target identity, task/goal justification and relevant revisions before producing AuthorizedAction. Only isolated Executor has external mutation credentials.

Injected case: executor applies external effect but connection times out before acknowledgement.

Expected result: `UNKNOWN_OUTCOME`; no blind retry; reconciliation query/verification required. A retry uses same ActionIntentID and a new AttemptID only after semantics permit.

Acceptance property: **no external side effect can bypass authority/commit and timeout cannot cause duplicate mutation by default**.

## 6.6 Scenario WS-004 — Topology equivalence

Run WS-001/002/003 twice:

1. bounded modules co-located where allowed;
2. Commit and Continuity accessed through remote adapters/processes.

Canonical semantic outcomes/invariants must be equivalent. Timing and expected temporary unavailability may differ; domain meaning must not.

Acceptance property: **process extraction does not require domain rewrite**.

## 6.7 Scenario WS-005 — No-LLM degraded continuity

Remove all cognitive providers.

System must still:
- identify existing actors/sessions where deterministically available;
- preserve events/state;
- keep canonical commitments/prospective schedules;
- perform deterministic authority/integrity checks;
- expose degraded capability state;
- avoid inventing new AI decisions/actions.

Acceptance property: **loss of cognition degrades intelligence, not continuity/integrity**.

## 6.8 Scenario WS-006 — Semantic evolution drill

Create a deliberately small v1→v2 contract/schema change in a non-critical skeleton concept. Prove:

- old historical object remains interpretable;
- new writer/readers use new version;
- unsupported semantics are explicit, not silently defaulted;
- active live objects migrate/validate;
- derived projections rebuild;
- rollback/forward-fix mode is documented.

Acceptance property: **architecture evolution is tested as a transformation, not merely promised**.

## 6.9 Foundation Exit Criteria

Foundation V1 is eligible for freeze when all are true:

1. Fresh Codex session can implement a bounded feature from repository artifacts alone.
2. Cross-owner DB write is physically denied.
3. Wrong-project mutation fails even under adversarial cognition proposal.
4. Stale/revoked authority cannot create AuthorizedAction.
5. Duplicate/replay does not duplicate external side effects in covered semantics.
6. Future obligation survives workflow-engine loss/rebuild.
7. Core remains continuity-capable without any LLM.
8. Same semantic scenarios pass in at least two process topologies.
9. Provider can be swapped/faked without domain contract change.
10. Declared and observed architecture graphs match or all drift has registered findings.
11. One semantic contract migration drill succeeds.
12. Architecture guardrail suite proves its own critical enforcement with negative tests.


---

# 7. UNRESOLVED_QUESTIONS.md

These questions are intentionally unresolved. Codex must not silently turn temporary assumptions into permanent architecture.

| ID | Question | Status | Temporary V1 position | Blocking? | Revisit trigger |
|---|---|---|---|---|---|
| UQ-001 | Exact split of `Work` into Goal/Task/Decision modules | RESEARCH | One canonical Work owner for V1 | No | Contract churn/co-change/consistency pressure |
| UQ-002 | Artifact metadata as separate module vs platform service | PROPOSED | Keep separate semantic owner if persistence begins | No | First large artifact integration |
| UQ-003 | Exact NATS subject taxonomy | DEFERRED | Define only subjects required by skeleton | No | First durable cross-owner event |
| UQ-004 | Exact Temporal workflow topology | DEFERRED | Temporal adapter behind Continuity; canonical prospective state outside | No | WS-002 implementation |
| UQ-005 | gRPC vs another remote transport for internal calls | DEFERRED | Contracts language-neutral; choose simplest baseline during remote drill | No | WS-004 |
| UQ-006 | Extent of canonical event archive vs per-owner transition history | RESEARCH | Do not event-source everything; retain meaningful events/outbox | No | Replay/recovery requirements emerge |
| UQ-007 | Formal policy engine technology | LATER | Deterministic typed Authority/Commit rules in Go V1 | No | Policy complexity outgrows code safely |
| UQ-008 | Vector store implementation | LATER | Search indexes derived; no foundation dependency | No | Epistemic retrieval slice |
| UQ-009 | Redis requirement | LATER | Optional cache only; correctness must not depend on it | No | Performance evidence |
| UQ-010 | Full Identity merge/split production workflow | EXTENSION_POINT | IDs/lineage schema must not preclude it; test simplified correction later | No | Multi-source identity pressure |
| UQ-011 | Portfolio/Trajectory/Responsibility primitives promotion | RESEARCH | Not Core V1 | No | Repeated distinct lifecycle/authority need |
| UQ-012 | Self-development automation | LATER | Development Control Plane external/manual-governed | No | Foundation + safe change/recovery mature |
| UQ-013 | Multi-user organization governance | LATER | Actor/Principal/Scope designed generally; expose single-user V1 if desired | No | Actual shared workspace requirement |
| UQ-014 | Canonical wire codec longevity | RESEARCH | Versioned schema/envelope; initial protobuf acceptable, not eternal identity | No | First non-Go module or major semantic migration |
| UQ-015 | Exact data retention/privacy policy engine | RESEARCH | Store scope/provenance/sensitivity hooks; implement concrete policies per product deployment | No | Product/legal requirements |

## 7.1 Spec-gap protocol

If implementation encounters a semantically material unknown not listed here, Codex emits a `SpecificationGap` with:

- exact scenario;
- current contract insufficiency;
- smallest temporary safe behavior if one exists;
- whether work can continue independently;
- proposed alternatives without choosing permanent architecture.

No architecture gap is solved by creating an unowned table, generic JSON object, cross-module direct read/write, or hidden provider-specific field.
\n\n---\n\n# 8. IMPLEMENTATION ORDER / NEXT TASKS\n\nThe first implementation sequence after this freeze pack is deliberately narrow:\n\n1. Create repository skeleton and protected architecture paths.\n2. Implement Architecture Registry validator and Go import boundary linter.\n3. Create PostgreSQL schemas/roles and negative ACL tests.\n4. Define strong IDs, revision/envelope primitives and platform outbox/inbox foundations.\n5. Define V1 semantic state machines and owner-local repository contracts for WS-001..003 only.\n6. Implement deterministic/fake cognition adapter and typed proposals.\n7. Build WS-001 Focus Isolation end-to-end.\n8. Build isolated Commit/Test-Executor path and WS-003.\n9. Build canonical Continuity/Prospective subset and WS-002.\n10. Add in-process/remote adapter contract suites and execute WS-004.\n11. Execute no-LLM and semantic migration drills WS-005/006.\n12. Only after Foundation Exit Criteria pass, expand into broader Epistemics/Context Compiler/Codex integration.\n\n**Codex must not be given a task like “implement the whole assistant”.** Each step above becomes a versioned Task Packet with a bounded architecture delta.\n