Strict Governance Laws
Relevant source files
The following files were used as context for generating this wiki page:
Strict Governance Laws represent the inviolable engineering framework and behavioral mandates governing all development activities within the flext-oracle-wms repository. These laws establish a zero-tolerance environment for technical debt, ensuring that every modification to the codebase maintains the integrity of the Single Source of Truth (SSOT), adheres to Railway-Oriented Programming (ROP) via the r pattern, and survives a comprehensive suite of automated quality gates.
The governance model is divided into the Universal Agent Engineering Core (P0-P29) and the Universal Agent Law, which collectively bind both human developers and AI agents to absolute architectural compliance. This system ensures that tests validate configurations by construction, documentation remains a living artifact, and "Done" is defined only by objective evidence of success.
Sources: AGENTS.md:7-14, src/README.md:81-87
Universal Engineering Core (P0 - P29)
The Universal Engineering Core establishes the fundamental principles for handling configuration, tests, and execution state. A primary directive is P0, which mandates that tests must validate configuration changes by construction. Hardcoding, freezing, or assuming current values in tests is strictly prohibited; instead, tests must read from the same typed SSOT used by production.
Sources: AGENTS.md:16-29
Core Operational Principles
| Law ID | Name | Description |
|---|---|---|
| P1 | Truth with Evidence | Claims require exact commands, exit status, and decisive output. |
| P2 | Research before Mutation | Current authority and implementation owners must be read before any change. |
| P4 | Root Cause | Changes must hit the canonical owner; no shims, suppressions, or bypasses. |
| P7 | Continuous Green | No completion while the project is broken; requires Ruff, Pyrefly, and Pyright. |
| P14 | Living Documentation | Every change updates affected docs in the same PR; stale docs are defects. |
| P17 | Canonical Command Surface | All actions must run through make verbs or documented CLI; no ad-hoc tools. |
Sources: AGENTS.md:31-89, README.md:46-48
Verification and Validation Flow
The project enforces a strict "Fix Forward" policy where clobbering or reverting shared work is forbidden. The following diagram illustrates the lifecycle of a task under strict governance.
This flow ensures that every change is evidenced-based and avoids destructive reverts of concurrent work.
Sources: AGENTS.md:34-44, AGENTS.md:129-135
Universal Agent Law (Portable Core)
The Portable Core is an inviolable set of rules that apply to every agent and session. It mandates a "Zero-Tolerance / Strict-Total" approach where root causes 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 a source of truth is absent.
Sources: AGENTS.md:109-127
Implementation Constraints
- Strict, Most-Restrictive Typing: Using
Anyor suppressing type errors is forbidden. Types must be fixed at the source. - SOLID & YAGNI: No speculative parameters or dead branches. Code must respect the Single Responsibility and Dependency Inversion principles.
- No Workarounds: Directives like
# type: ignoreor blanket# noqaare prohibited unless they carry a one-line documented justification. - Singer Protocol Compatibility: Transformations must maintain compatibility with data pipeline standards.
Sources: AGENTS.md:137-139, AGENTS.md:155-161, src/flext_oracle_wms/README.md:107-112
Quality Gates and CI Enforcement
Governance is programmatically enforced through pyproject.toml configurations and make verbs. The project requires 90%+ test coverage and 95%+ type coverage.
Tooling Configuration
The following table summarizes the strict linting and typing requirements:
| Tool | Mandate | Configuration Note |
|---|---|---|
| Ruff | ALL rules enabled | Zero tolerance for linting violations across src, tests, and examples. |
| MyPy | Strict Mode | check_untyped_defs = true, strict_equality = true. |
| Pyright | Type Checking | typeCheckingMode = "strict", mandatory for CI. |
| Bandit | Security | Security scanning integrated into the make security verb. |
Sources: pyproject.toml:104-124, pyproject.toml:414-430, src/README.md:81-87
Sequence of a Governed Submission
The interaction between the Orchestrator and implementation agents follows a strict sequence to maintain the integrity of the integration branch.
Sources: AGENTS.md:57-65, AGENTS.md:163-167
Summary of Governance Significance
The Strict Governance Laws of flext-oracle-wms prevent the accumulation of technical debt by transforming engineering best practices into hard, automated constraints. By mandating evidence-first truth, root-cause resolution, and living documentation, the project ensures that its high-volume Oracle WMS integration remains reliable, performant, and maintainable across multi-agent sessions.
Sources: AGENTS.md:195-201, src/README.md:100-105