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.

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 <task-file> for Tier B+ tasks when available.

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.

Domovoy Gen2 execution governance

When the active task is a Gen2 packet, read the canonical documents before editing:

• docs/DOMOVOY_CONSTITUTION.md
• architecture/GEN2_TARGET_ARCHITECTURE.md
• architecture/GEN2_CANONICAL_DATA_MODEL.md
• development/GEN2_MIGRATION_MAP.md
• development/GEN2_MASTER_PLAN.md
• development/GEN2_EXECUTION_CONTRACT.md

The active task packet and development/GEN2_TASK_INDEX.md define execution order. PRE-GEN2-000 freezes the V1 baseline; ARCH-GEN2-000 accepts Gen2 governance; later GEN2-* packets must not be started automatically. Gen2 architecture and ownership changes are permitted only within the active packet's declared scope and authority. Default validation is FAST; MILESTONE or FULL is required only when the selected packet explicitly says so.