Governance & Engineering Standards
Relevant source files
The following files were used as context for generating this wiki page:
Governance and Engineering Standards in the flext-tap-oracle-oic project establish a rigorous framework for technical conduct, architectural consistency, and quality assurance. These standards ensure that all contributions—whether from human developers or AI agents—adhere to a "Zero-Debt" baseline, utilizing Single Source of Truth (SSOT) principles and strictly typed Python implementations for Oracle Integration Cloud (OIC) data extraction.
The scope of these standards covers core engineering conduct (Universal Agent Law), unified architectural patterns (ProjectModels), and specific validation protocols for OIC resources. By enforcing these rules, the project maintains high reliability in enterprise ETL environments while preventing technical drift and coordination conflicts.
Sources: AGENTS.md:1-12, README.md:16-32, src/flext_tap_oracle_oic/models.py:16-25
Universal Agent Law & Conduct
The project operates under the Universal Agent Law, an inviolable core of engineering conduct that applies to all AI agents and users. This law mandates a "Strict-Total" approach to quality and root-cause resolution.
Core Conduct Principles
| Principle | Description |
|---|---|
| Zero-Tolerance | Fix root causes generically; no dead code, stubs, or legacy "carve-outs". |
| Fix-Forward-Only | Never revert shared work; accept the current state and fix issues in new commits. |
| Stay In Scope | Execute only requested tasks; do not perform unrequested refactors or adjacent fixes. |
| Evidence Before Done | "Done" requires objective evidence (commands, exit codes, and output logs). |
| Strict Typing | Use the most restrictive types possible; no Any or unchecked casts without justification. |
Sources: AGENTS.md:16-75
Conflict Resolution & Coordination
When multiple agents or developers share a working tree, coordination is managed through a committed task board. The "Fix-Forward-Only" rule is critical here: agents are strictly forbidden from using git reset --hard or git restore on shared work to prevent the destruction of in-flight changes.
The diagram illustrates the standard workflow for multi-agent coordination and scoped landing of work.
Sources: AGENTS.md:78-84, AGENTS.md:118-125
Architectural & Engineering Principles
The project follows standard software engineering patterns to ensure maintainability and modularity, specifically focusing on the SOLID principles and the YAGNI (You Ain't Gonna Need It) philosophy.
Unified Class Patterns (SSOT)
The repository implements a "Single Source of Truth" (SSOT) pattern. For example, FlextTapOracleOicUtilities serves as the unified namespace for all conversion, validation, and domain-specific operations, extending base classes from flext-core and flext-meltano.
- SRP (Single Responsibility Principle): Each model and utility has a narrow, well-defined purpose.
- DIP (Dependency Inversion Principle): Logic depends on abstractions (e.g.,
FlextApiprotocols) rather than hard-wired implementations. - YAGNI: Speculative parameters and future-hooks are prohibited; only code required for the current task is built.
Sources: AGENTS.md:92-101, src/flext_tap_oracle_oic/utilities.py:22-30
Pydantic Validation Standards
All data models (Entities) use Pydantic (v2.11+) for strict runtime validation. Entities such as OicIntegrationEntity include model_validator blocks to enforce logical constraints that cannot be captured by type hints alone.
@u.model_validator(mode="after")
def validate_integration_entity(self) -> Self:
"""Validate OIC integration entity."""
if not self.integration_id:
msg = "Integration ID is required"
raise ValueError(msg)
if self.execution_count is not None and self.execution_count < 0:
msg = "Execution count cannot be negative"
raise ValueError(msg)
return self
Sources: src/flext_tap_oracle_oic/_models/_integration.py:126-136
Quality Gates & Tooling
Engineering standards are enforced through a series of "Quality Gates" and managed dependencies defined in pyproject.toml.
Managed Toolchain
The project uses hatchling as the build backend and maintains a highly specific set of development dependencies to enforce linting, formatting, and type safety.
| Category | Tools Used |
|---|---|
| Linting & Formatting | ruff, black, isort, autoflake |
| Type Checking | mypy, pyright, pyrefly |
| Testing | pytest, pytest-cov, hypothesis |
| Documentation | mkdocs, mkdocs-mermaid2-plugin |
Sources: pyproject.toml:6-10, pyproject.toml:50-100
Security & Sanitization
Governance standards mandate the sanitization of sensitive data during extraction. The OicStreamConfiguration model defaults sanitize_sensitive_data to True to prevent accidental leakage of credentials or PII from OIC endpoints.
Sources: src/flext_tap_oracle_oic/_models/_stream_config.py:72-76
Domain-Specific Standards (OIC)
Specific standards are applied to the construction and validation of Oracle Integration Cloud interactions.
API URL Construction
Endpoints must be built using the build_oic_api_url utility, which validates the base URL against OCI region patterns and ensures correct resource paths.
The sequence illustrates the validation steps required before an API URL is considered safe for use.
Sources: src/flext_tap_oracle_oic/utilities.py:40-66, src/flext_tap_oracle_oic/constants.py:28-35
Health & Performance Metrics
Entities are required to provide health summaries. The OicIntegrationEntity computes an error_rate and assigns a health_status (e.g., HEALTHY or DEGRADED) based on execution_count versus error_count.
Sources: src/flext_tap_oracle_oic/_models/_integration.py:93-124
Summary of Constraints
Governance and engineering standards in this repository prioritize immutability of history (fix-forward), strict validation at the boundary (Pydantic models), and standardized tooling to maintain a robust and predictable codebase for Oracle Integration Cloud integrations. All changes must be verified with objective evidence before being landed in the scoped working tree.
Sources: AGENTS.md:1-12, README.md:1-10