Governance & Engineering Rules
Relevant source files
The following files were used as context for generating this wiki page:
Governance and engineering rules for the flext-db-oracle project are defined by the Universal Agent Law, a set of inviolable principles that bind both human developers and AI agents. These rules ensure architectural integrity, strict type safety, and a "Zero-Tolerance" approach to technical debt. The project is built on Clean Architecture principles, ensuring clear boundaries between the application, domain, and infrastructure layers.
Sources: AGENTS.md:6-14, src/README.md:32-55
1. Universal Agent Law
The Universal Agent Law serves as the core of engineering conduct for the repository. It is self-contained and takes precedence over all other configurations, except for explicit instructions from a live user.
1.1 Core Directives
- Zero-Tolerance / Strict-Total: All root causes must be fixed generically and cleanly. Superseded code must be removed in the same cycle. Bypasses, stubs, and legacy classification of new failures are strictly forbidden.
- Fix-Forward-Only: Reverting shared work via
git reset,git checkout, orgit stash(to hide others' work) is forbidden to prevent destroying in-flight work in multi-agent environments. - Evidence Before Done: "Done" requires objective evidence, including commands, exit codes, and output lines. Partial or speculative results are unacceptable.
Sources: AGENTS.md:16-52
1.2 Engineering Protocol Flow
The following diagram illustrates the standard protocol for handling blocked operations or deviations from plan.
The workflow ensures that any ambiguity or blocked tool leads to an immediate halt and user consultation rather than a workaround.
Sources: AGENTS.md:54-72
2. Architectural Governance
The project enforces Clean Architecture and SOLID principles to maintain enterprise-grade standards for Oracle database integration.
2.1 Layered Architecture
| Layer | Description | Key Modules |
|---|---|---|
| Application | Facades and CLI entry points | api.py, cli.py |
| Domain | Core logic and metadata models | metadata.py, types.py |
| Infrastructure | Resource management and monitoring | connection.py, observability.py, settings.py |
| Foundation | System-wide constants and exceptions | constants.py, exceptions.py |
Sources: src/README.md:9-30
2.2 Integration Rules
- Single Source of Truth (SSOT): One authoritative source per fact; system must fail loud if absent.
- Dependency Inversion (DIP): High-level modules must depend on abstractions (Protocols/Interfaces), not concretions.
- Railway-Oriented Programming (r[T]): All service operations must use the
rresult pattern for error handling.
Sources: AGENTS.md:86-102, src/README.md:57-62
3. Development & Quality Gates
Strict quality standards are enforced via automated tools and manual checklists.
3.1 Coding Standards
- Type Safety: 95%+ type annotation coverage is required. Strict MyPy compliance is mandatory.
- Naming: Public classes must use the
FlextDbOracleprefix. Constants must useORACLE_. - Imports: Only direct imports are allowed; aliases for metadata operations are forbidden.
Sources: src/README.md:65-79, pyproject.toml:98-120
3.2 Automated Validation Gates
Developers must execute canonical make verbs to pass quality gates before landing code:
| Command | Tooling | Threshold |
|---|---|---|
make lint | Ruff | All rules enabled |
make type-check | MyPy / Pyright | Strict mode, no untyped code |
make test | Pytest | 90%+ Coverage |
make security | Bandit / pip-audit | Zero critical vulnerabilities |
Sources: src/README.md:104-114, README.md:37-39
3.3 Git Landing Protocol
Once work is validated (green), it must be landed immediately.
- Use explicit pathspecs for
git add. - Commit as the user (no agent/bot attribution or
Co-Authored-Bytrailers). - Perform fast-forward
push. - Recover stale tasks via git history if coordination is lost.
Sources: AGENTS.md:104-122
4. Testing Governance
Testing is divided into three distinct layers, ensuring that business logic is validated in isolation before integration.
The testing hierarchy prevents slow database-dependent tests from blocking the initial development feedback loop.
Sources: tests/README.md:23-50
4.1 Mocking Strategy
- Unit Tests: Must use mocks/patches for external dependencies (e.g.,
sqlalchemy.create_engine). - Integration Tests: Must use a real Oracle database (typically via Docker).
- End-to-End: Must validate the complete chain from CLI to database without stubs.
Sources: tests/README.md:188-204
5. Maintenance & Coordination
In multi-agent environments, coordination is performed through a committed task board located at <repo>/.agents/coordination/tasks.md. Agents must claim a task with an ownership lease and heartbeat the lease during execution.
5.1 Destructive Operations
Destructive actions are heavily restricted:
- Archive, Don't Destroy: Files should be moved to
.bakrather than deleted. - Privilege Escalation:
sudo,su, or changing ownership requires explicit user confirmation. - Network: Fetching arbitrary network resources is forbidden without confirmation.
Sources: AGENTS.md:124-135
Engineering rules within flext-db-oracle prioritize predictability and safety over speed. By adhering to the Universal Agent Law and SOLID principles, the project ensures that contributions remain maintainable and technically sound across distributed development sessions.