Governance & Agent Law
Relevant source files
The following files were used as context for generating this wiki page:
Governance within the flext-target-oracle-wms project is dictated by a set of inviolable rules known as the Universal Agent Law. This law binds both human developers and AI agents (such as Claude, Codex, or GitHub Copilot) to a strict-total engineering conduct. The primary purpose is to maintain a zero-debt baseline, ensure high-fidelity technical execution, and prevent the degradation of the codebase through "temporary" fixes or workarounds.
The governance framework extends beyond behavioral rules into technical enforcement. This is achieved through automated quality gates, strict module structure requirements, and standardized development dependencies. These mechanisms ensure that every contribution adheres to the project's architectural standards, including Single Source of Truth (SSOT) and SOLID principles.
Sources: AGENTS.md:4-16, README.md:32-40
Universal Agent Law (Portable Core)
The core of the project's governance is a self-contained block of rules that applies to every session and project type. It cannot be relaxed for convenience or speed.
1. Zero-Tolerance & Root Cause
The system mandates a "Strict-Total" approach where the root cause of any issue must be fixed generically and cleanly. Superseded code must be removed in the same cycle as the replacement, and the system must "fail loud" if essential configuration or contracts are missing. Bypasses such as TODO, FIXME, or hardcoded stubs are strictly forbidden.
Sources: AGENTS.md:18-30
2. Fix-Forward & Scope Control
Reverting shared work is forbidden to prevent destroying the in-flight work of other agents. Developers must accept the current state and fix forward. Additionally, agents must stay strictly within the requested scope; unrequested refactors or "obvious improvements" are treated as defects.
Sources: AGENTS.md:32-38, AGENTS.md:47-49
3. Verification & Honesty
A task is only "Done" when the complete chain is validated with objective evidence, including exit codes and output lines. Speculative or unverified results are prohibited. If a step was skipped or a workaround was required, it must be explicitly reported.
Sources: AGENTS.md:51-56
4. Programming & Typing Standards
The law enforces the use of the most restrictive types possible. Use of Any, bare object, or suppression directives (e.g., # type: ignore) is forbidden unless accompanied by a documented one-line justification.
Sources: AGENTS.md:68-71
Technical Enforcement
Governance is enforced programmatically through the test suite and build configuration.
Module Governance Checks
The project includes specific tests to ensure the internal structure of the module remains compliant with engineering laws. Key checks include:
- No Module-Level Loggers: Forbidden to prevent hidden global state.
- Unapproved Top-Level Functions: Functions are restricted to approved entrypoints to prevent API sprawl.
- Namespace Integrity: Ensures that local Singer message models do not shadow standard ones.
Sources: tests/unit/test_module_governance.py:46-86
Quality Gates
The project defines canonical make verbs (check, test, val, docs) that act as quality gates. These gates utilize a suite of tools configured in pyproject.toml to enforce linting, type-checking, and security standards.
| Tool | Purpose | Configuration Source |
|---|---|---|
ruff | Linting and Formatting | [tool.ruff] |
mypy | Static Type Checking | [tool.mypy] |
codespell | Spelling Verification | [tool.codespell] |
deptry | Dependency Validation | [tool.deptry] |
bandit | Security Linting | [project.optional-dependencies] |
Sources: README.md:32-35, pyproject.toml:132-480
Multi-Agent Coordination Flow
When multiple agents or developers work on the same tree, they must coordinate through a committed task board and follow a specific landing protocol.
The diagram above shows the standard lifecycle of an agent's task from inception to landing.
Sources: AGENTS.md:79-85, AGENTS.md:58-66
Engineering Principles
The project adheres to four primary engineering principles that govern all architectural decisions:
- SSOT (Single Source of Truth): One authoritative source per fact. Reference, never duplicate.
- SOLID: Strict adherence to SRP, OCP, LSP, ISP, and DIP. Fat interfaces and god-objects are considered defects.
- YAGNI (You Ain't Gonna Need It): Build only what is necessary now; no speculative parameters or dead branches.
- DI / DIP (Dependency Injection / Inversion): Depend on abstractions (Protocols) and inject collaborators; no hard-wired construction inside business logic.
Sources: AGENTS.md:73-82
Operational Protocol
Blocked-Operation Protocol
If a tool or command is blocked by security hooks or sandbox restrictions, the agent must:
- Stop immediately.
- Diagnose the block in one sentence.
- Provide the exact command to the user.
- Wait for the user's output before continuing.
Sources: AGENTS.md:58-66
Archival vs. Destruction
Destructive commands are discouraged. Prefer moving files to <file>.bak rather than deleting. Actions like force-pushing or rewriting history require explicit user confirmation.
Sources: AGENTS.md:94-100
Conclusion
The "Governance & Agent Law" of the flext-target-oracle-wms repository provides a rigorous framework that ensures high-quality, maintainable code. By combining behavioral mandates (Agent Law) with technical enforcements (Quality Gates and Governance Tests), the project maintains a predictable and professional engineering environment suitable for mission-critical Oracle WMS integrations.
Sources: AGENTS.md:4-16, examples/README.md:121-127