ADR 26011: Formalization of the Mandatory Script Suite Workflow

Title¶

Mandating a synchronized 1:1:1 ratio for Scripts, Tests, and Documentation.

Status¶

Proposed

Date¶

2026-01-26

Context¶

As the repository grows, documentation drift and untested utility scripts create significant maintenance debt. Developers often follow outdated instructions or encounter broken scripts that lack corresponding test cases.

Current architectural decisions established Python as the standard for hooks ADR 26001 and pre-commit as the orchestration framework ADR 26002. We now require a formal mechanism to ensure that no script is introduced or modified without its accompanying verification and instructional artifacts.

Here we are decoupling the Script Suite Concept—the mandatory 1:1:1 ratio of Code:Test:Doc—from the Tiered Commit Validation logic ADR 26003. This ADR focuses exclusively on the structural integrity of the tools/ directory and the automation required to enforce it.

The challenge identified is Knowledge Fragmentation. When a script is updated but its test or documentation is not, the repository’s “Smallest Viable Architecture” (SVA) degrades into technical debt. By formalizing the “Suite” as a single atomic unit, we move from passive documentation to Active Specification Enforcement.

Decision¶

We will enforce the Script Suite as a mandatory unit of development. A “Suite” is defined by the existence of three interconnected files following a strict naming convention:

1. The Script: Located in tools/scripts/<name>.py.

2. The Test: Located in tools/tests/test_<name>.py.

3. The Documentation: Located in tools/docs/scripts_instructions/<name>_py_script.md and its .ipynb pair.

Enforcement Mechanisms:

• Local Enforcement: A custom Python script will run via pre-commit. It will fail the commit if a script is staged without its corresponding test and documentation, or if a script is modified without the documentation also being staged.

• CI/CD Enforcement: The same validation will run as a “Hard Gate” in the GitHub Actions quality.yml workflow to ensure remote state integrity.

Consequences¶

Positive¶

• Zero-Drift Documentation: Documentation is kept synchronized with code changes through mandatory co-staging.

• Reliability: Every utility script in the repository is guaranteed to have an associated test suite.

• Reduced Cognitive Load: Engineers can rely on the fact that documentation exists and is accurate for every tool in tools/scripts/.

Negative¶

• Development Friction: Small, one-off utility scripts now require the overhead of a test and a doc file. Mitigation: The naming convention allows for the exclusion of clearly marked “experimental” or “temp” directories if necessary.

• Latency: The pre-commit hook adds a check for file existence/staging status. Mitigation: Python execution logic will be kept lean to stay within the 100-200ms window established in ADR 26001.

• “Documentation Quality Decay.” While the system enforces the existence of a documentation file, it cannot easily enforce its meaningfulness. You may end up with “empty” documentation files just to satisfy the hook. * Mitigation: Incorporate a minimum word count or a template-matching check (e.g., must contain # Purpose and # Usage headers) within check_script_suite.py.

Alternatives¶

• Manual PR Checklists: Rejected as they are prone to human error and do not provide immediate feedback during the commit cycle.

• Docstring-only Documentation: Rejected because complex scripts require the rich formatting and interactive capabilities provided by MyST/Jupyter documentation.

References¶

• ADR 26001: Use of Python and OOP for Git Hook Scripts

• ADR 26002: Adoption of the Pre-commit Framework

• tools/docs/scripts_instructions/README.ipynb: Section on “Script and its Suite”

Participants¶

1. Vadim Rudakov

2. Gemini (Senior DevOps Systems Architect)