75 lines
3.4 KiB
Markdown
75 lines
3.4 KiB
Markdown
# 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.
|