Governance & Universal Agent Law
Relevant source files
The following files were used as context for generating this wiki page:
The Governance & Universal Agent Law within the flext-observability project represents the inviolable core of engineering conduct and architectural standards. It is designed as a portable, agent-agnostic framework that binds both human developers and AI agents (such as Claude, Cursor, or GitHub Copilot) to a strict set of rules. This governance ensures that all observability implementations—ranging from metrics and tracing to health checks—adhere to high-integrity engineering principles like SOLID, SSOT, and YAGNI.
The scope of this law covers every aspect of the repository, including core package development in src/flext_observability/, testing strategies defined in tests/, and infrastructure configurations in pyproject.toml. By enforcing a "Zero-Tolerance" policy for technical debt and workarounds, the project maintains a professional baseline necessary for enterprise monitoring and telemetry.
Sources: AGENTS.md:5-15, README.md:21-25, src/README.md:46-52
Core Conduct: The Universal Agent Law
The Universal Agent Law is a self-contained block of rules that governs all session types and project activities. It prioritizes root-cause solutions over temporary fixes and mandates objective evidence before a task is considered "Done."
Fundamental Principles of Conduct
- Zero-Tolerance / Strict-Total: Root causes must be fixed generically and validated in the same turn. Superseded code must be removed immediately.
- Fix-Forward-Only: Reverting shared work is forbidden to prevent destroying in-flight work from other agents.
- Root Cause Only: Prohibits the use of
TODO,FIXME, stubs, or suppression directives like# type: ignorewithout documented justification. - Evidence Before Done: A task is only complete when validated with command output, exit codes, and objective results.
Sources: AGENTS.md:17-57
Engineering Standards Hierarchy
The governance model relies on four primary engineering principles applied to all observability modules:
| Principle | Description | Implementation Requirement |
|---|---|---|
| SSOT | Single Source of Truth | One authoritative source per fact; fail loud if absent. |
| SOLID | Clean Architecture | Respect SRP, OCP, LSP, ISP, and DIP. Avoid god-objects. |
| YAGNI | You Ain't Gonna Need It | No speculative parameters or dead branches. |
| DI / DIP | Dependency Inversion | Depend on abstractions; inject collaborators via FlextContainer. |
Sources: AGENTS.md:92-102, src/flext_observability/README.md:129-135
Operational Governance Flow
The project utilizes a structured flow for code changes, ensuring that every modification is validated against quality gates and documented standards.
The diagram above illustrates the standard execution flow required by Rule 6 (Execute As Planned) and Rule 7 (Blocked-Operation Protocol).
Sources: AGENTS.md:65-88, README.md:21-25
Architectural Governance
The architectural governance enforces a layered approach to the observability package, separating concerns between domain logic and infrastructure.
Layered Architecture Requirements
The repository follows Clean Architecture principles as detailed in the source code organization:
- Domain Layer: Contains core entities (Metric, Trace, Alert) with rich business logic and validation.
- Application Layer: Coordinates services like
FlextMetricsServiceandFlextTracingService. - Interface Layer: Provides the public API surface and factory patterns (
FlextObservabilityMasterFactory). - Infrastructure Layer: Handles data access patterns and external system adapters.
Sources: src/README.md:25-42, src/flext_observability/README.md:21-65
Implementation Constraints
- Railway-Oriented Programming (ROP): All operations MUST return a Result pattern (
r[T]). - Type Safety: MyPy strict mode is mandatory, aiming for 100% type coverage.
- Test Coverage: A minimum of 95% test coverage is required for all public APIs.
Sources: src/README.md:49-59, src/flext_observability/README.md:154-159
Development & Multi-Agent Coordination
In environments where multiple agents share a working tree, specific coordination protocols are enforced to maintain repository integrity.
Task Coordination Logic
Agents must coordinate through a committed task board, typically located at <repo>/.agents/coordination/tasks.md.
The sequence diagram shows the coordination mechanism defined in Rule 11 for shared working trees.
Sources: AGENTS.md:112-120
Git Governance (Rule 10 & 13)
- Immediate Landing: Scoped work must be committed and pushed immediately after green validation.
- Attribution: Commits must be written as the user, with no bot or agent attribution strings (e.g., no "Generated by...").
- Preservation: Destructive commands are discouraged; files should be archived as
.bakrather than deleted. Reverting shared history requires explicit user confirmation.
Sources: AGENTS.md:104-110, AGENTS.md:129-136
Quality Gates and Standards
The project configuration in pyproject.toml defines the technical enforcement of governance laws.
| Category | Tool / Requirement | Configuration |
|---|---|---|
| Linting | Ruff | ALL rules enabled; zero tolerance for violations. |
| Typing | MyPy | Strict mode; warn_unreachable = true. |
| Security | Bandit | Mandatory scanning for all source code. |
| Coverage | Pytest-cov | fail_under = 25 (global) / 95% (module target). |
| Dependencies | Deptry | Verification of managed dependency groups. |
Sources: pyproject.toml:130-170, src/README.md:63-71, tests/README.md:162-168
Summary
The Governance & Universal Agent Law serves as the foundational "constitution" for flext-observability. By mandating strict-total conduct, SSOT architecture, and objective validation, it ensures the platform remains robust and maintainable. All contributors, whether human or AI, are bound by these laws to eliminate technical debt and ensure that every change is a "Fix-Forward" toward a more stable observability ecosystem.
Sources: AGENTS.md:5-15, src/flext_observability/README.md:7-13