m/Assistant

Fork 0

Files

T

m 9b136621ef

CI / test (push) Successful in 7m31s

Details

feat: implement Foundation V1 walking skeleton

2026-08-16 15:22:49 +03:00

41 KiB

Raw Permalink Blame History

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 Иерархия архитектурной власти

Architecture Constitution.
Accepted ADR / Foundation Decision.
Machine-readable Architecture Registry.
Versioned semantic contracts and state machines.
Module architecture specification.
Codex Task Packet.
Implementation and examples.

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

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

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

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

Task lifecycle (minimum)

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

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

Prospective item lifecycle

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.

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:

Go import graph against may_depend_on/forbidden edges.
No /modules/*/domain imports from adapters/runtime/provider packages.
Migration scanner rejects cross-owner writes/FKs/triggers/views unless explicit approved exception.
PostgreSQL role tests prove owner isolation.
Diff-scope check against Codex Task Packet.
Protected-path rule.
Public contract change detection.
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:

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:

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:

bounded modules co-located where allowed;
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:

Fresh Codex session can implement a bounded feature from repository artifacts alone.
Cross-owner DB write is physically denied.
Wrong-project mutation fails even under adversarial cognition proposal.
Stale/revoked authority cannot create AuthorizedAction.
Duplicate/replay does not duplicate external side effects in covered semantics.
Future obligation survives workflow-engine loss/rebuild.
Core remains continuity-capable without any LLM.
Same semantic scenarios pass in at least two process topologies.
Provider can be swapped/faked without domain contract change.
Declared and observed architecture graphs match or all drift has registered findings.
One semantic contract migration drill succeeds.
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\nCodex 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

41 KiB Raw Permalink Blame History Unescape Escape