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.

Deployment safety (production mutation)

• Production mutation in normal devctl workflow must go through deploy prepare then deploy apply.
• deploy apply is rejected when required inputs are MISSING, EMPTY, INVALID, UNKNOWN, UNRESOLVED, or STALE.
• Ambient shell state is not accepted as authoritative required production input; required values must come from an explicit durable source (for example --env-file/manifest-classified bootstrap path).
• A prepared plan must be current (inputs, compose, context, revision binding) before apply proceeds.

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.