Engineering Governance & Agent Laws
Relevant source files
The following files were used as context for generating this wiki page:
Engineering Governance within the flext-tap-oracle-wms project is dictated by a set of inviolable "Agent Laws" designed to ensure consistent, high-quality, and maintainable code. These laws bind both AI agents and human contributors to a strict standard of technical conduct, emphasizing root-cause fixes, rigorous verification, and zero-debt development.
The governance framework establishes a "Zero-Tolerance" policy for workarounds and temporary fixes, requiring all changes to be validated with objective evidence before being considered complete. This system is central to the project's ability to maintain enterprise-grade standards while undergoing architectural transitions, such as the planned simplification of the core module from 26 files down to 6-8 files.
Sources: AGENTS.md:7-14, src/flext_tap_oracle_wms/README.md:95-103
Universal Agent Law (Portable Core)
The Universal Agent Law serves as the foundational engineering contract for the repository. It is self-contained and binds any AI agent (e.g., Claude, Cursor, GitHub Copilot) or user to a specific behavioral protocol that cannot be relaxed for convenience or perceived triviality.
Core Directive Categories
| Category | Requirement |
|---|---|
| Zero-Tolerance | Root causes must be fixed generically; superseded code must be removed immediately; fallback/legacy wrappers are forbidden. |
| Fix-Forward-Only | Reverting shared work is forbidden to prevent destroying other agents' in-flight work. |
| Root Cause Only | No TODOs, stubs, or suppression directives (like # type: ignore) without one-line justifications. |
| Evidence Before Done | "Done" requires objective evidence: command, exit code, and output validation. |
| Blocked Operations | If a tool is blocked, the agent must stop, diagnose, and hand the exact command to the user. |
Sources: AGENTS.md:16-56
Conflict Resolution Flow
When an agent encounters ambiguity or shared state conflicts, it must follow a specific escalation protocol.
This diagram illustrates the mandatory pause-and-ask protocol required when an agent encounters ambiguity or blocked operations, ensuring no unilateral hacks are applied.
Sources: AGENTS.md:58-75
Technical Standards & Quality Gates
The governance model enforces strict technical requirements to maintain the integrity of the Singer-compliant tap. These standards are checked at various "Quality Gates" using canonical make verbs.
Engineering Principles
- SSOT (Single Source of Truth): One authoritative source per fact; fail loud if absent.
- SOLID: Strict adherence to Object-Oriented design principles; God-objects are considered defects.
- YAGNI (You Ain't Gonna Need It): No speculative parameters or future-hooks.
- DI/DIP: Collaborators must be injected; hidden globals are forbidden.
- Restrictive Typing: Use of
Anyor bareobjectis prohibited; types must be fixed at the source.
Sources: AGENTS.md:77-100, src/flext_tap_oracle_wms/README.md:112-118
Quality Gate Selectors
The project defines specific thresholds and automated checks that must pass before code landing:
make check: Linting and static analysis (Ruff, MyPy strict mode).make test: Execution of unit and integration tests.make val: Validation of configuration and schema contracts.make docs: Generation of documentation via MkDocs and Mkdocstrings.
Sources: README.md:46-51, pyproject.toml:290-315
Multi-Agent Coordination Protocol
Because multiple agents may share a single working tree, the governance framework includes a coordination protocol to prevent race conditions and code overwrites.
Task Board Management
Agents must coordinate through a committed task board (e.g., .agents/coordination/tasks.md). The lifecycle of a task follows a strict ownership model:
- Claim: Entry of ownership and lease in the task board before editing.
- Heartbeat: Periodic updates to the lease to signify active work.
- Finish: Setting status to
doneorblocked. - Recover: Stale tasks are recovered by inspecting
git log.
Sources: AGENTS.md:107-115
Git Landing and Commit Standards
Verified work must not remain only in the working tree. Agents are granted durable authorization for normal scoped landing under specific conditions:
- Fast-Forward Only: Pushes must be fast-forward; history rewrites are strictly forbidden without user confirmation.
- No Attribution: Commits must be written as the user; no "Generated by bot" trailers or
Co-Authored-Bytags. - Pathspecs: Use explicit pathspecs during
git addto avoid landing unrequested changes.
Sources: AGENTS.md:102-105, AGENTS.md:117-124
Testing Governance
The testing strategy is a critical component of engineering governance, ensuring that the Oracle WMS tap remains Singer-compliant and resilient.
Test Isolation and Mocking
Governance dictates that unit tests must have No External Dependencies. This requires:
- Mocking HTTP: No actual network calls to Oracle WMS are permitted in unit tests.
- Environment Isolation: Environment variables and file systems must be mocked.
- Deterministic Results: Tests must be reliable and complete in milliseconds.
Sources: tests/unit/README.md:160-166, tests/README.md:151-160
Coverage Thresholds
The project enforces high coverage standards, though current status indicates a need for remediation:
| Component | Minimum Requirement | Target |
|---|---|---|
| Unit Tests | 90% Line Coverage | 95% + Branch Coverage |
| Integration Tests | 90% Scenarios | Full Interaction Coverage |
| Overall Project | 20% (Fail Under) | 90% (Actual Target) |
Sources: tests/unit/README.md:144-148, pyproject.toml:98-102, tests/README.md:275-279
Governance Implementation Logic
The following sequence diagram represents how an agent interacts with the governance rules during a standard code change cycle.
This diagram depicts the mandatory integration of governance checks at every stage of the development lifecycle, from task claiming to final push.
Sources: AGENTS.md:10-120, README.md:40-44
Summary of Governance Significance
Engineering Governance and Agent Laws in this repository are not merely suggestions but architectural requirements. By enforcing a "Zero-Debt" baseline and a "Fix-Forward-Only" workflow, the project ensures that its high complexity—currently 26 files for a Singer tap—remains manageable and stable during its planned refactoring into a more streamlined architecture. Compliance with these laws is the primary metric for successful contributions, whether from human developers or AI agents.
Sources: src/flext_tap_oracle_wms/README.md:93-100, AGENTS.md:16-20