Storage and Scratch Law
Relevant source files
The following files were used as context for generating this wiki page:
Storage and Scratch Law defines the engineering standards for data persistence, isolation, and temporary workspace management within the flext-quality ecosystem. It establishes strict boundaries for where data lives, how it is managed during maintenance cycles, and the lifecycle of "scratch" or temporary artifacts generated during quality analysis and agent orchestration.
This law ensures that the flext-quality platform maintains high professional integrity by enforcing "zero residue" policies and "storage isolation." These principles prevent data leakage between different analysis phases and ensure that every implementation is researched against canonical documentation before effects are applied.
Sources: AGENTS.md:120-128, AGENTS.md:144-155, README.md:18-22
Storage Architecture and Governance
The project implements storage isolation as a core engineering rule. All persistent state must reside within defined writable authorities to honor the Single Source of Truth (SSOT) principle. In flext-quality, this is evidenced by the separation of configuration, logs, and report directories.
Persistence Boundaries
The system distinguishes between three primary storage types:
- Canonical Trackers: Local Dolt DBs used for issue tracking via the
bd(beads) tool. - Maintenance Storage: Directories dedicated to backups and reports generated during scheduled tasks.
- Log Storage: Rotated log files for auditability.
The diagram shows the hierarchical isolation of storage artifacts to prevent residue and maintain the SSOT.
Sources: AGENTS.md:123-128, src/flext_quality/_models/flextqualitymodels_part_02.py:108-115
Maintenance and Backup Configuration
Maintenance storage is governed by the MaintenanceConfig model. This structure defines where the system writes reports and stores backups during scheduled maintenance runs.
Storage Parameters
The following table describes the configuration fields for maintenance storage:
| Field | Type | Description |
|---|---|---|
reports_dir | str | Destination directory for maintenance reports. |
backup_dir | str | Destination directory for backups created during maintenance. |
log_file | str | Filesystem path for the maintenance log. |
max_log_size | str | Maximum size before log rotation (default: 10MB). |
retention_days | int | Retention period for rotated logs (default: 30 days). |
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:84-106, src/flext_quality/_models/flextqualitymodels_part_02.py:108-147
Scratch Space and Zero Residue
The "Zero Residue" policy is a non-optional requirement under the Strict Execution rule. It mandates that no temporary files or "scratch" artifacts remain after a process completes. This is critical for agent orchestration where tools like search_code or execute_hook may generate intermediate data.
Implementation Requirements
- Preflight before effects: Validate storage readiness before performing writes.
- Atomic effects: Ensure storage changes are committed entirely or not at all.
- Causal cleanup: Propagate termination signals to ensure subprocesses do not leave orphaned scratch files.
The sequence diagram illustrates the lifecycle of a maintenance task, emphasizing the preflight check and the final cleanup to satisfy the Zero Residue law.
Sources: AGENTS.md:144-155, .claude/rules/storage.md:1-10
Utility Operations for Storage
The FlextQualityUtilities class provides standardized methods for interacting with the filesystem and handling input/output while adhering to storage laws. Specifically, it manages the flow of data through stdin and shell commands with strict timeouts.
Key Utility Functions
read_stdin(): Safely reads JSON input for hooks, catching exceptions to prevent unhandled residue.run_shell_command(): Executes shell operations with a defaultHOOK_TIMEOUT_MS(300,000ms or 300s) to prevent hanging processes from occupying storage locks.format_hook_output(): Serializes hook results into a standard JSON format for the next actor in the chain.
Sources: src/flext_quality/utilities.py:133-140, src/flext_quality/utilities.py:142-159, src/flext_quality/_models/flextqualitymodels_part_02.py:34-45
Conclusion
Storage and Scratch Law ensures that flext-quality operates as a clean, predictable orchestration platform. By enforcing storage isolation and zero residue, the system prevents technical debt from accumulating in the form of orphaned files or inconsistent data states. Developers must use the MaintenanceConfig and LoggingConfig models to define persistence and rely on FlextQualityUtilities for safe filesystem interactions.