Tooling & Quality Gates

The autoswe repository enforces code quality and architectural discipline through a suite of vendored, stdlib-only Python tools that operate as pre-commit and pre-push gates. These tools ensure that the codebase remains maintainable by limiting file complexity, eliminating AI-generated prose artifacts, and preventing accidental pushes of development work to the public release repository. The enforcement chain is anchored by a pre-push hook that orchestrates these checks, ensuring that no code violating the 1000-line ceiling or prose hygiene standards can leave the local environment.

Prose Hygiene Gate

The tools/check_prose_hygiene.py script acts as a linting gate for all tracked text files, specifically targeting “AI-generated-prose tells” that degrade readability and professionalism. It operates in two modes: a default reporting mode that fails if offenders are found, and a --fix mode that deterministically repairs auto-fixable issues.

The gate scans for four categories of violations:

1. Dash Family: Em-dashes, en-dashes, horizontal bars, and figure dashes are flagged as AI-generated punctuation. The --fix mode collapses these into plain hyphens.
2. Decorative Emoji: Emoji characters are stripped from comments and documentation files (.md, .rst, .txt) where they are considered decorative. Functional emoji in UI markup or code strings are preserved.
3. Narration Comments: Comments that merely restate the next action (e.g., “# Build the payload”) without explaining why are flagged. This check excludes documentation files and multi-line comment blocks to avoid orphaning explanations.

Files can opt out of these checks by including the marker prose-hygiene: allow in their content. The tool excludes binary, media, generated, and lock files from scanning.

File Ceiling Enforcement

The tools/check_file_ceiling.py tool enforces a strict line-count limit on hand-authored code files to prevent excessive complexity. It defines a maximum of 1000 lines per file (MAX_FILE_LINES = 1000) and fails if any code file exceeds this threshold.

The gate applies to specific hand-authored languages: Python, Go, JavaScript, TypeScript, Astro, Shell, CSS, and HTML. It explicitly excludes:

• Binary and media files (e.g., .png, .pdf, .so).
• Generated lockfiles (e.g., package-lock.json, Cargo.lock).
• Vendored or cached directories (e.g., node_modules, .venv, __pycache__).
• Minified assets (.min.js, .min.css).

The tool uses a stable logical line count by splitting text on newlines, ensuring accurate measurement regardless of trailing newline conventions. Offenders are reported in worst-first order, sorted by line count descending.

Pre-Push Gate Integration

The pre-push git hook, located in .githooks/pre-push, serves as the central enforcement point that integrates the above tools with repository access control. It is installed via git config core.hooksPath .githooks.

The hook performs three critical checks before allowing a push:

1. File Ceiling Check: It runs tools/check_file_ceiling.py. If any code file exceeds 1000 lines, the push is blocked.
2. Prose Hygiene Check: It runs tools/check_prose_hygiene.py. If any AI-speak, dashes, or narration comments are detected, the push is blocked.

If any check fails, the hook prints a detailed error message and exits with a non-zero status, preventing the push. Developers can bypass these checks using git push --no-verify, but this is intended only for intentional public pushes.