Governance Synthesis & Language Extension
Relevant source files
The following files were used as context for generating this wiki page:
Governance Synthesis and Language Extension in FLEXT Quality provides the mechanisms for enforcing engineering laws and extending quality rules across the ecosystem. This system orchestrates agent tooling, manages declarative quality rules, and ensures that code changes adhere to project-specific governance policies. The framework uses a Single Source of Truth (SSOT) approach where governance artifacts such as AGENTS.md and YAML-based rule definitions drive the automated validation and synthesis processes.
Sources: AGENTS.md:1-10, README.md:1-15
Engineering Governance Framework
The project operates under a strict "Parent workspace law" that establishes the universal engineering core. Every implementation must research repository owners, remove unnecessary scope (YAGNI), and elect a writable authority. Governance is synthesized from global skills, parent root laws, and local scope deltas.
Sources: AGENTS.md:1-5, AGENTS.md:46-55
Governance Synthesis Flow
The following diagram illustrates how governance instructions are synthesized and applied to the agent runtime.
The diagram shows the hierarchy of governance sources merging into a session capsule that controls execution gates.
Sources: AGENTS.md:1-10, AGENTS.md:40-45
Core Engineering Principles
FLEXT Quality enforces several non-optional policies for all projected agents:
| Policy | Description | Source |
|---|---|---|
| Fail Loud | Failures must escape with traceback and cause; no silent catch. | AGENTS.md:65-70 |
| No Fallback | Invalid configuration or results fail without fallback or normalization. | AGENTS.md:75-80 |
| SSOT | Elect one writable authority; every other copy is a projection. | AGENTS.md:50 |
| YAGNI | Remove scope without a current requirement or consumer. | AGENTS.md:49 |
Rules Engine Architecture
The FlextQualityRulesEngine handles declarative, YAML-based rule validation. It allows for checking both physical files and raw content strings against a set of enabled rules. This engine acts as the primary mechanism for extending the language-specific quality checks within the project.
Sources: src/flext_quality/rules/engine.py:15-30
Rule Validation Logic
When a file is validated, the engine reads the text content and iterates through all enabled rule definitions. If a rule includes a regular expression pattern, the engine compiles and searches the content. Matches are recorded as violations containing severity and recommended actions.
This sequence shows the interaction between the user, the rules engine, and the filesystem during a validation run.
Sources: src/flext_quality/rules/engine.py:53-85
Declarative Rule Structure
Rules are defined using the RuleDefinition model, which provides a structured schema for quality checks.
| Field | Type | Description |
|---|---|---|
name | str | Unique identifier for the rule. |
type | RuleType | Category (e.g., content, style, accessibility). |
pattern | str | None | Regex pattern for matching violations. |
action | str | Action to take on match (error/warning). |
enabled | bool | Whether the rule is active. |
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:535-560
Language Rules and Content Modification
The project supports language extensions via mod-rules (e.g., sed.yaml), which define find-and-replace patterns for specific files like AGENTS.md. These rules maintain alignment between documentation and the generated runtime profiles.
Sources: config/rules/mod/sed.yaml:1-12
Content Analysis Model
Content quality is tracked via ContentMetrics, which measures structural and readability aspects of documentation.
class ContentMetrics(_WebModels.ManagedModel):
"""Content quality metrics for a documentation file."""
word_count: int = _WebModels.Field(default=0)
sentence_count: int = _WebModels.Field(default=0)
avg_words_per_sentence: float = _WebModels.Field(default=0.0)
readability_score: float = _WebModels.Field(default=0.0)
has_code_blocks: bool = _WebModels.Field(default=False)
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:588-610
Quality Model Hierarchy
FLEXT Quality uses a split model architecture to manage domain complexity while adhering to per-module Line of Code (LOC) limits. The models are divided into Part01 and Part02, composed through Method Resolution Order (MRO).
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:10-20, src/flext_quality/_models/flextqualitymodels_part_02.py:25-30
Key Model Namespaces
- Quality Metrics: Typed metrics for documentation audit results including total issues and severity breakdowns.
- Threshold Config: Limits for documentation age, word count, and file size.
- Link Validation: Configuration for checking external, internal, and GitHub-specific links.
- Validation Config: Execution limits for validation runs, such as requests per second and burst limits.
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:35-80, src/flext_quality/_models/flextqualitymodels_part_01.py:300-350
Conclusion
Governance Synthesis and Language Extension form the backbone of the FLEXT Quality orchestration platform. By combining strict engineering laws in AGENTS.md with a declarative YAML rules engine, the system ensures that both code and documentation remain compliant with project standards. The modular architecture of the quality models and the automated synthesis of governance capsules provide a scalable foundation for agent-led development and quality enforcement.