AGENTS.md

Rama main · réplica de lectura del repositorio original.

# Repository conventions

- For development, run `python -B dev/scripts/repo_status.py` once and flag open work, including the current feature branch, before editing. Prefer an existing unfinished feature branch. If the user has not selected a branch, name the existing candidates and ask which to use or whether to create a new one; an existing selection remains valid. Avoid worktrees for local development; create one only with explicit user approval. New feature branches start from `origin/dev`. Use `dev/skills/apex-development/SKILL.md` for investigation, a concrete plan and implementation approval; existing explicit approval counts. Contributor merge, release, refactoring, documentation and cleanup skills live in `dev/skills`, with generated discovery entries in `.agents/skills`. Customer workflows remain in `app/skills`.

- Merge/release completion includes deleting the task's merged temporary remote and local branches, while preserving `main`, `dev` and active work. Follow `dev/docs/developer-workflow.md#branch-lifecycle`; after release synchronization, verify equal content unless newer feature work entered `dev`. Different merge commit IDs are normal.

- Use English for source comments, identifiers, documentation, examples and user-facing messages in the repository. Conversation language can follow the user.
- Keep the scheduling core independent of any real customer. Place optional source adapters and domain extensions in customization modules.
- Commit only deliberately synthetic examples. Do not copy or rename customer exports into fixtures. Do not commit customer names, identifiers, production data, credentials, private endpoints, model checkpoints or derived vector stores.
- Read credentials and deployment-specific values from the environment. Keep `.env` files and generated outputs out of version control.
- Prefer Bash (`.sh`) for repository shell helpers, including Git Bash on Windows. Keep shell scripts executable with LF line endings and quote paths so checkouts with spaces work.
- Follow the root `LICENSE` (APEX Source Available License 1.1), `LICENSING.md` and the matching summary in `app/docs/legal/pricing.md`. The root license is the canonical public grant; separate commercial and contributor agreements require express acceptance and are not supplied as unfinished repository templates. Do not invent different thresholds or prices, add a permissive license, claim OSI open-source status or introduce per-operation, per-user or per-run metering.
- Read `app/docs/architecture/README.md` before implementation work. It maps the current modules, evaluation flow, state boundaries and affected tests. Keep architecture documentation aligned with executable behavior; historical v2 evidence belongs in `dev/docs/migration-audit.md`. The v2 source and its execution harnesses have been removed.
- The runnable Rust implementation is in `app/core` (`apex-engine` crate), with API/CLI entry points, orchestration and persistence in `app/middleware/{api,control,data}` and clients in `app/ui/{mcp-app,desktop}` ([control platform](app/docs/control-platform.md)). Input schemas are unversioned and ship with the main application release; do not add separate format-version fields or historical schema compatibility paths. See `app/docs/implementation.md`, `app/docs/data-model.md` and `app/docs/architecture/declarative-scheduling.md` for operational and semantic contracts.
- For a scheduling rule or objective change, update typed input, readiness checks, evaluation, objective/heuristic semantics and independent validation together. Add semantic, negative and corrupted-output tests; never disable hard rules to improve a score.
- Run the Rust commands from `app/`: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` for Rust changes. Rebuild the release binary before MCP/browser verification. Report measured results separately from design goals and optimality claims.
- Keep `.apex` artifacts and machine-specific MCP configuration out of distribution. New customization fixtures must be synthetic. Keep migration evidence consolidated in `dev/docs/migration-audit.md`; removal of v2 does not establish complete migration parity. Generated reports remain local.

- `app/` is the independent customer source distribution with its own manifests, lockfiles and complete license. Do not add parent-directory dependencies. Read `dev/docs/repository-layout.md` for contributor tooling and run `python -B dev/scripts/check_standalone.py` after changing distribution boundaries.