Universal Engineering Core

Relevant source files

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

• AGENTS.md
• README.md
• src/flext_quality/rules/engine.py
• src/flext_quality/_models/flextqualitymodels_part_01.py
• src/flext_quality/_models/flextqualitymodels_part_02.py
• src/flext_quality/utilities.py
• examples/basic/simple_analysis/README.md

The Universal Engineering Core defines the foundational principles and architectural standards for the flext-quality package. It enforces strict implementation patterns, including YAGNI (You Ain't Gonna Need It), SSOT (Single Source of Truth), and SOLID principles, to ensure a unified orchestration platform for quality workflows.

This core system governs how agents and developers interact with code generation, project checks, and tool orchestration. It provides a canonical set of rules that supersede auxiliary tracking or documentation, ensuring that every implementation adheres to the project's engineering law.

Sources: AGENTS.md:50-70, README.md:15-25

Core Engineering Principles

The engineering core mandates seven specific requirements for every implementation:

1. Research: Verify repository owners, dependencies, and canonical documentation.
2. YAGNI: Remove any scope that lacks a current requirement or consumer.
3. SSOT: Elect one writable authority; all other copies must be generated projections.
4. SOLID: Apply principles only to responsibility or dependency boundaries undergoing change.
5. Ownership: Implement through the owner and simplify without weakening behavior.
6. Refactor: Remove duplication and "god" components.
7. Validation: Exercise runtime behavior and run all native gates before completing a landing cycle.

Sources: AGENTS.md:55-66

Execution and Failure Policy

The system applies a "Strict Execution" policy that is universal and non-optional.

Policy	Requirement
Fail Loud	The first exception must escape the CLI with a traceback and cause.
No Fallback	Avoid symptom workarounds; fix the root cause at the owner.
Atomic Effects	Ensure operations are atomic and do not leave residue.
Preflight	Validate environment and configuration before executing effects.

Sources: AGENTS.md:70-80, AGENTS.md:105-115

Rules Engine Architecture

The FlextQualityRulesEngine facilitates YAML-based declarative rules validation. It loads rule definitions and validates project content against regular expression patterns.

The diagram shows the logic flow of the rules engine during a validation cycle.
Sources: src/flext_quality/rules/engine.py:35-70

Rule Definition Structure

Rules are defined in YAML and mapped to the RuleDefinition model.

• Name: Unique identifier for the rule.
• Type: Category (e.g., content, style, link, accessibility).
• Pattern: Regular expression used for matching.
• Action: Response taken upon a match (e.g., error or warning).

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:465-485

Quality Domain Models

The domain models are split into multiple parts to maintain module size limits. They provide typed structures for audit metrics, style violations, and validation results.

Audit and Validation Metrics

The AuditMetrics model tracks the overall quality of documentation and code.

Field	Type	Description
quality_score	int	Overall score from 0 to 100.
total_issues	int	Total count of found issues.
severity_breakdown	Mapping[str, int]	Issue counts by severity level.
files_analyzed	int	Number of files inspected.

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:38-65

Link and Content Validation

The system includes specialized models for validating documentation links and content structure.

The diagram represents the relationship between validation results and specific issue types.
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:530-550, src/flext_quality/_models/flextqualitymodels_part_02.py:270-320

Utility Orchestration

The FlextQualityUtilities (aliased as u) provide the runtime mechanisms for shell execution, pattern compilation, and JSON handling.

Key Utility Operations

• Shell Execution: run_shell_command executes commands with a defined timeout (default 30,000ms).
• Pattern Management: compile_pattern handles regex compilation with support for IGNORECASE, MULTILINE, and DOTALL flags.
• Hook Communication: format_hook_output and parse_hook_input standardize JSON communication for agent hooks.

Sources: src/flext_quality/utilities.py:55-100, src/flext_quality/utilities.py:150-180

# Example of hook output formatting
def format_hook_output(
    *,
    continue_exec: bool = True,
    message: str | None = None,
    blocked_reason: str | None = None,
) -> str:
    output = {"continue": continue_exec}
    if message:
        output["systemMessage"] = message
    if blocked_reason:
        output["blockedReason"] = blocked_reason
    return u.MUTABLE_OPTIONAL_FEATURE_FLAG_MAPPING_ADAPTER.dump_json(output).decode()

Sources: src/flext_quality/utilities.py:102-120

Summary

The Universal Engineering Core ensures that flext-quality remains a robust and predictable orchestration platform. By enforcing strict ownership rules, SSOT principles, and automated quality gates through its rules engine and domain models, the core prevents architectural drift and maintains high engineering standards across the FLEXT ecosystem.