Governance & Engineering Standards
Relevant source files
The following files were used as context for generating this wiki page:
Governance and Engineering Standards within the flext-oracle-oic project establish a rigorous framework for technical conduct, code quality, and operational consistency. These standards are anchored by the "Universal Agent Law," which mandates strict adherence to root-cause fixes, evidence-based validation, and a "fix-forward-only" philosophy for all contributors, including AI agents and human developers.
Sources: AGENTS.md:7-13, README.md:16-19
Universal Agent Law (Core Conduct)
The repository operates under a strict set of inviolable rules designed to maintain high engineering integrity across collaborative environments. This law ensures that any modifications—whether automated or manual—adhere to professional standards of reliability and clarity.
Primary Directives
- Zero-Tolerance & Strict-Total: Engineers must fix root causes rather than symptoms. Superseded code must be removed immediately to prevent "dead code" accumulation. Fallbacks, stubs, and "TODO" comments are strictly forbidden as final solutions.
- Fix-Forward-Only: Reverting shared work is prohibited. All contributors must accept the current state and apply fixes on top of it to avoid destroying in-flight work from other agents.
- Evidence-Based Completion: A task is only considered "Done" when validated with objective evidence, including specific commands, exit codes, and output lines.
Sources: AGENTS.md:15-46, AGENTS.md:57-65
Validation and Execution Flow
The following diagram illustrates the standard protocol for executing tasks and validating results under the Universal Agent Law.
The flow emphasizes that if an operation is blocked or deviates from the plan, the agent must stop and consult the user rather than attempting a workaround.
Sources: AGENTS.md:67-75, AGENTS.md:77-94
Engineering Principles
The project adheres to several industry-standard architectural principles to ensure the codebase remains maintainable and scalable.
| Principle | Description |
|---|---|
| SSOT | Single Source of Truth. Each fact has one authoritative source (e.g., constants in constants.py). |
| SOLID | Adherence to SRP, OCP, LSP, ISP, and DIP. Interfaces and protocols are preferred over concrete implementations. |
| YAGNI | "You Ain't Gonna Need It." No speculative parameters or dead branches are allowed. |
| DI / DIP | Dependency Injection/Inversion. Business logic must not hard-wire construction of collaborators. |
Sources: AGENTS.md:103-113, src/flext_oracle_oic/constants.py:15-30
Validation Standards & Thresholds
The engineering standards define specific validation logic for Oracle OIC integrations and performance monitoring.
Performance Metric Assessment
Performance monitoring utilities enforce specific thresholds to ensure integration health.
Data Integrity Rules
Field validation is mandatory for all integration configuration data. The project uses a FieldValidationPlan to ensure consistent data structures.
| Field | Requirement | Validation Rules |
|---|---|---|
| Name | Required | Length: 1-100; Regex: ^[a-zA-Z0-9_\-\s]+$ |
| Version | Optional | Format: XX.XX.XXXX (Regex: ^\\d{2}\\.\\d{2}\\.\\d{4}$) |
| Status | Optional | Must be in: ACTIVATED, DEACTIVATED, DRAFT, PUBLISHED, RUNNING, STOPPED, ERROR |
Sources: src/flext_oracle_oic/_utilities/oracle_oic.py:46-64, src/flext_oracle_oic/constants.py:158-175
Development & Quality Gates
The project utilizes automated quality gates and standardized development dependencies to enforce code quality.
- Typing: Strict, most-restrictive typing is required. The
mypyandpyrighttools are configured to error onAnytypes and unannotated parameters. - Linting: Managed through
ruff, enforcing rules likeALLselect with specific ignores for standard compliance. - CI/CD Hooks: Canonical
makeverbs (check,test,val,docs) serve as the contract for passing quality gates.
Sources: pyproject.toml:150-170, pyproject.toml:235-250, README.md:38-40
Summary
The Governance & Engineering Standards for flext-oracle-oic create a zero-debt baseline for development. By enforcing the Universal Agent Law alongside SOLID and SSOT principles, the project ensures that integrations are robust, typed, and verifiable. Automated validation thresholds for performance and data integrity further safeguard the stability of the Oracle OIC Extension.