Strict Execution, Fail Loud & Zero Residue
Relevant source files
The following files were used as context for generating this wiki page:
Strict execution governs the runtime behavior of the flext-quality orchestration platform. It enforces a non-optional set of policies that prevent silent failures, partial state residue, and unevidenced success. These policies ensure that every project check, code generation task, or agent-led modification operates under absolute professional integrity.
The core engineering law requires that developers research repository owners, remove unnecessary scope (YAGNI), and exercise runtime behavior through native gates before changing phases. Strict execution applies across all package boundaries, including the orchestration of Claude Code tooling and quality workflows.
Sources: AGENTS.md:76-89, AGENTS.md:111-120
Core Policies of Strict Execution
The flext-quality system applies eight cumulative policies to every projected agent and project. These policies cannot be relaxed, deferred, or skipped by any project-specific rule.
| Policy Name | Description |
|---|---|
| Fail Loud | The first exception must escape the CLI with a full traceback and cause. Normalizing failure or catching exceptions to return "green" results is prohibited. |
| No Fallback | Systems must fail if the primary intended path is unavailable. Fallbacks, retries, and compatibility shims for invalid inputs are considered defects. |
| Preflight Before Effects | Components must validate authorization, configuration, and readiness before performing any side effects. |
| Required Environment | Execution requires a valid environment; if variables or dependencies are missing, the system must fail without attempting to guess defaults. |
| Atomic Effects | Operations must either complete entirely or leave no trace of partial execution. |
| Causal Subprocess Propagation | Errors in child processes must propagate immediately to the parent caller. |
| No Keyring | Secret management must be explicit; implicit keyring probes are prohibited. |
| Zero Residue | Temporary files, processes, or state changes must be cleaned up or never committed if an operation fails. |
Sources: AGENTS.md:86-89, AGENTS.md:111-125
Validation and Rule Enforcement
The FlextQualityRulesEngine implements these policies by validating code against declarative YAML rules. It enforces severity levels to ensure that blocking violations prevent further execution.
Rule Engine Flow
The following diagram illustrates how the rules engine enforces strict validation during a quality check.
The engine ensures that if a rules_path is invalid or a file cannot be read, the system returns a failure result immediately rather than skipping the file.
Sources: src/flext_quality/rules/engine.py:46-75, src/flext_quality/rules/engine.py:127-142
Failure Handling and Professional Integrity
Professional integrity is defined as the refusal to hide blockers or bypass gates. If an external token validation is required but the token is missing, the system records the state as NOT EXECUTED, never "green". If the gate is explicitly invoked, the missing token causes an immediate escape with a traceback.
Execution Results and Contracts
Data models in FlextQualityModelsPart02 define the contracts for execution results. The ExecutionResult model captures standard output and error but prioritizes the success boolean and exit_code.
class ExecutionResult(_WebModels.ManagedModel):
"""Structured result payload from a command execution."""
success: bool = _WebModels.Field(
description="Whether the executed command completed successfully.",
)
exit_code: int = _WebModels.Field(
description="Process exit code returned by the executed command.",
)
stdout: str = _WebModels.Field(default="")
stderr: str = _WebModels.Field(default="")
Sources: AGENTS.md:92-108, src/flext_quality/_models/flextqualitymodels_part_02.py:534-547
Quality Gates and Test Reliability
The test suite enforces strict execution through high coverage requirements and deterministic behavior. Tests must validate both success and failure scenarios using the should/when pattern.
Testing Standards
- Minimum 90% Coverage: Required for all source modules.
- No Flaky Tests: Tests must be deterministic and repeatable.
- Fail Fast: The
ErrorHandlingConfigallows forfail_fastbehavior during maintenance tasks, stopping immediately on the first failure. - Traceback Visibility: CLI commands (
Check/Validate) are designed to escape with the first exception.
Summary of Runtime Evidence
Strict execution requires that state alone proves no intention. Every implementation must prove the producer contract and output. If a cross-boundary failure occurs, the developer must fix the owner if invalid or the receiver if it fails to conform. Workarounds for symptoms are classified as defects. In the flext-quality ecosystem, this ensures that the "zero-debt baseline" is maintained across all orchestration paths.
Sources: AGENTS.md:81-85, examples/basic/simple_analysis/README.md:28-35