Governance & Universal Agent Law

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• pyproject.toml
• src/flext_target_ldif/writer.py
• src/flext_target_ldif/models.py
• src/flext_target_ldif/target.py

Introduction

The Governance & Universal Agent Law within the flext-target-ldif project establishes an inviolable core of engineering conduct and operational protocols. It serves as a portable set of rules that bind all AI agents (such as Claude, Cursor, or GitHub Copilot) and human contributors to ensure high-quality, root-cause-driven development. This governance framework is designed to prevent technical debt, maintain a Single Source of Truth (SSOT), and coordinate multi-agent interactions within a shared working tree.

This law is self-contained and applies to every session and project type, prioritizing engineering integrity over convenience or speed. It ensures that every modification adheres to strict typing, SOLID principles, and rigorous validation before being considered "done".

Sources: AGENTS.md:5-15, README.md:23-35

Universal Agent Law Core

The core of the governance model is a set of zero-tolerance rules regarding engineering conduct. These rules mandate that contributors always address root causes and never use workarounds or stubs to bypass gates.

Strict-Total Engineering Conduct

• Root Cause Resolution: All fixes must be generic, clean, and validated with exit codes and relevant output.
• Dead Code Elimination: Superseded code must be removed in the same cycle as its replacement.
• Single Source of Truth (SSOT): Systems must fail loudly if the authoritative source of identity, config, or contract is missing.
• Prohibited Workarounds: The use of TODO/FIXME, stubs, fakes, or "compatibility wrappers" is strictly forbidden.

Sources: AGENTS.md:17-27, AGENTS.md:40-45

Fix-Forward-Only Protocol

In environments where multiple agents share a working tree, reverting state is prohibited as it may destroy in-flight work. The governance model enforces a "fix-forward" approach.

The diagram shows the decision flow for resolving issues while strictly adhering to the Fix-Forward-Only rule.
Sources: AGENTS.md:29-38

Operational & Coordination Protocols

Governance extends beyond code quality into how tasks are claimed, executed, and validated within the flext-target-ldif repository.

Validation and Evidence

"Done" is strictly defined by objective evidence. Partial or speculative results are never accepted. Validation requires:

1. Command executed.
2. Exit code verified.
3. Relevant output lines matched.

Sources: AGENTS.md:53-61

Multi-Agent Coordination Structure

Coordination is handled through a committed task board located in the repository history. Agents must claim tasks with a lease entry and commit small, frequent updates.

Protocol Component	Requirement	Source File
Task Claiming	Lease entry in .agents/coordination/tasks.md	AGENTS.md:100-104
Commit Style	Fast-forward push; no agent/bot attribution	AGENTS.md:92-98
State Recovery	Rebuild state from git log	AGENTS.md:104-106
Ambiguity	Stop and ask one focused question	AGENTS.md:108-111

Universal Engineering Principles

The project adheres to specific architectural standards that are enforced by the governance model.

• SOLID & YAGNI: Principles focusing on single responsibility and avoiding speculative parameters or dead branches.
• Dependency Injection (DI/DIP): Logic must depend on abstractions (protocols/interfaces) rather than hard-wired constructions.
• Strict Typing: The system mandates the most restrictive types possible. Usage of Any or object is considered a defect unless accompanied by a one-line justification.

This diagram represents the relationship between high-level engineering principles and the daily conduct of agents within the system.
Sources: AGENTS.md:80-90, AGENTS.md:75-78

Implementation in flext-target-ldif

The governance rules are applied technically through the implementation of models and targets that enforce configuration and validation rules at runtime.

Configuration Validation Logic

The FlextTargetLdif class implements validate_config, which serves as a programmatic gate for the settings defined in FlextTargetLdifSettings.

# From src/flext_target_ldif/target.py:73-84
    def validate_config(self) -> None:
        """Validate the target configuration."""
        config_dict = (
            dict(self._test_config) if self._test_config else dict(self.settings)
        )
        if self._test_config is not None and "output_file" not in config_dict:
            msg = "Output file is required"
            raise ValueError(msg)
        # ... validation logic continues

Sources: src/flext_target_ldif/target.py:73-84, src/flext_target_ldif/models.py:90-110

Resource Governance

Destructive commands are governed by an "Archive, Don't Destroy" policy. Deletion is replaced by moving files to a .bak extension. Privilege escalation (sudo) and history rewriting are strictly forbidden without explicit user confirmation.

Sources: AGENTS.md:113-118

Summary

The Governance & Universal Agent Law is the foundational framework for the flext-target-ldif project. It ensures that all contributors—human or AI—operate within a strict set of engineering standards that prioritize root-cause fixes, transparent validation, and multi-agent coordination. By enforcing SOLID principles, strict typing, and a "fix-forward" mentality, the project maintains a high-integrity codebase free of stubs, hacks, and unverified work.