# 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.