Project Governance & AI Directives
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the operational laws, engineering standards, and automation directives governing the development and maintenance of the mt5-docker project. It establishes a hierarchy of authority for AI agents and human contributors, ensuring technical integrity through strict validation gates, dependency management, and living documentation.
The governance structure is built upon the Universal Agent Engineering Core, which prioritizes evidence-based truth, root-cause resolution, and continuous environment health. These directives ensure that the dual-Python architecture (System 3.13 and Wine 3.12) remains stable and that all changes are independently validated before integration.
Sources: AGENTS.md:1-15, README.md:15-35
Universal Engineering Core
The project adheres to a set of sixteen fundamental laws that dictate how work is planned, executed, and validated. Central to this is the concept of "Truth with Evidence," where no claim of success is accepted without explicit command output and exit status verification.
Key Governance Principles
- Beads as Execution Truth: The
beads(bd) system is the sole authority for work plans, dependencies, and status tracking. GitHub serves as an external coordination mirror for PRs and CI. - Root Cause Resolution: Fallbacks, shims, and hardcoded bypasses are strictly prohibited. Every change must address the canonical owner of the logic.
- Continuous Green: No task is considered complete if the project or environment is left broken or partially migrated. This includes mandatory linting (Ruff), type checking (Pyright/Mypy), and test coverage.
- Separated Roles: The system distinguishes between Orchestrators (coordination and validation) and Workers (implementation). Merge and closure actions are restricted to orchestrator roles.
Sources: AGENTS.md:16-56, CLAUDE.md:12-25
Implementation Flow
The following diagram illustrates the lifecycle of a change request under the universal governance core:
This flow ensures that project knowledge is durable and never rebuilt per session, as mandated by the "Living Documentation" directive.
Sources: AGENTS.md:20-65, CLAUDE.md:20-23
AI Hub Inviolable Laws
AI agents operating within this repository are subject to the Strict Prelude rules. These are non-negotiable directives loaded before any agent action. Agents must escalate to the operator immediately if a gate blocks progress or if a rule cannot be followed cleanly.
Core Directives for Agents
| Directive | Description |
|---|---|
| Absolute Truth | Never claim "done" without exit codes and decisive output. |
| Research First | Inspect code and canonical sources before acting; no invented APIs. |
| FLEXT First | Use project facades backed by flext-core for Python operations. |
| Small Slices | Deliver work in independently validated units (hours, not days). |
| Stop on Blocker | Ask one precise question if authority conflicts arise. |
Sources: CLAUDE.md:1-10, AGENTS.md:57-73
Dependency Governance & Environment Management
The project implements a strict dependency strategy to manage its dual-Python architecture and ensure compatibility across development and production environments.
Dependency Strategy
- Local Development: Uses path dependencies (e.g.,
mt5linux = { path = "../mt5linux" }) to allow real-time iterations. - Production/CI: Automatically switches to git references via the
setup-dependencies.shscript. - Automation:
Dependabotis configured to track external dependencies while ignoring local path overrides.
Sources: README.md:105-125, scripts/setup-dependencies.sh:10-40
Dependency Configuration Management
The setup-dependencies.sh script acts as the idempotent gatekeeper for these configurations, detecting the environment and applying the correct mode.
Sources: scripts/setup-dependencies.sh:140-185, pyproject.toml:35-45
Validation & Quality Gates
Technical integrity is maintained through a hierarchy of validation tools and mandatory "Continuous Green" checks.
Tooling Matrix
The project uses specific tools for different layers of validation, as defined in the governance docs and pyproject.toml.
| Tool | Purpose | Configuration Scope |
|---|---|---|
| Ruff | Linting & Formatting | Line length 88, target Py313 |
| Pyright/Mypy | Static Type Analysis | Strict mode, Python 3.13 |
| Pytest | Runtime Validation | tests/ directory, 600s timeout |
| ast-grep (sg) | Structural Search | Repository-wide pattern matching |
Sources: pyproject.toml:5-25, CLAUDE.md:24-26, AGENTS.md:43-48
Standard Validation Commands
Agents and contributors are required to use the following make targets to ensure consistent gating:
make lint: Executes Ruff for style and logical errors.make typecheck: Runs Pyright/Mypy to verify type safety.make test: Executes the full test suite, including static and runtime categories.
Sources: CLAUDE.md:21-23, README.md:235-245
Project Constants and Business Domains
Governance extends to the organization of code constants. As evidenced in tests/constants.py, the project follows an advanced pattern of StrEnum and IntEnum nested within business domain namespaces.
Namespace Hierarchy
- Infrastructure: Manages ports (VNC 3000, gRPC 8001) and container names.
- Timing: Defines timeouts for Docker startup (300s) and health checks.
- Versioning: Maintains the
REQUIRED_VERSIONSset (Python, gRPC, NumPy, Wine Mono/Gecko). - Message: Standardizes user-facing skip reasons and error descriptions.
Sources: tests/constants.py:45-120, tests/constants.py:320-350
Conclusion
The governance framework of mt5-docker ensures that AI and human contributions are harmonized through a shared set of engineering laws. By enforcing root-cause fixes, evidence-based claims, and rigorous automated validation, the project maintains a "Production Ready" state while managing the complexities of a containerized MetaTrader 5 environment. Consistent use of the beads system and adherence to the Universal Engineering Core are required for all modifications to the codebase.
Sources: AGENTS.md:74-90, README.md:30-45