133 lines
6.0 KiB
Markdown
133 lines
6.0 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.**
|
|
|
|
## 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.
|