Assistant/AGENTS.md

AGENTS.md — Codex operating contract

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. 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 <task-file> 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:

Architecture Constitution > accepted ADR > Architecture Registry > Core Semantic Model > module architecture file > task packet > examples/comments.

Do not silently resolve a conflict. Return BLOCKED_BY_SPEC_GAP or BLOCKED_BY_ARCHITECTURE_GAP.

Hard prohibitions

• NO cross-module direct DB access.
• NO cross-owner SQL JOIN/FK/view/trigger by default.
• NO direct external mutation outside Commit/Executor boundary.
• NO model/provider call outside cognitive adapter/gateway boundaries.
• NO semantic durable timer implemented as time.After, unmanaged goroutine or in-memory queue.
• NO cross-module correctness depending on shared mutex, pointer, filesystem or process-local transaction.
• NO giant common, shared, generic Entity, generic Status, generic Manager, ServiceLocator, or map[string]any as a substitute for Core semantics.
• NO provider/runtime types in domain packages.
• NO weakening tests, architecture lints, DB ACLs, or guardrails to make a task pass.
• NO new third-party dependency in an ordinary feature task.
• NO protected-path modification unless the task explicitly grants Tier E authority.
• NO reading/copying literal passwords from other repositories into this repository.
• NO production secret in source, task packet, commit message, logs or tests.

Codex freedom

Inside the declared owner/module and allowed paths, choose ordinary local implementation details freely. Prefer explicit, typed, boring Go over reflection, metaprogramming or framework tricks.

Semantic duplication is preferable to false abstraction. Shared technical mechanisms may live under platform/; shared domain meaning may not.

When blocked

Valid terminal states include:

• BLOCKED_BY_SPEC_GAP
• BLOCKED_BY_ARCHITECTURE_GAP
• BLOCKED_BY_MISSING_CAPABILITY
• BLOCKED_BY_CONFLICT
• REQUIRES_MIGRATION_DECISION

Never “make it work somehow” by violating a boundary.

Git and deployment

• Canonical remote: https://git.cin.su/m/Assistant.git.
• Target deployment control plane: https://docker.cin.su (Portainer).
• This project must not use docker-test, test-docker, or docker-test.cin.su for builds, CI runners, tests, deployment, backups, or project data unless the user gives a new explicit project-specific authorization.
• Use configured credential helpers first; never echo secrets.
• If push/deploy credentials are unavailable, ask the user for the minimum needed access.
• Ordinary Codex work happens on a branch/worktree, never directly on protected main.

Required completion report

State:

• task ID/revision;
• changed paths/modules;
• contracts/schemas/events/dependencies/privileges touched;
• tests actually executed;
• 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.