Guardrail Workflow¶

Guardrails exist to turn repeated PR review findings into enforced checks. The goal is to catch high-confidence problems before review, without creating a second competing policy engine.

Canonical Ownership¶

Each blocking guardrail belongs in exactly one enforced layer:

Pitfall: if a rule only exists in prose or only exists in the shell script, it will drift. Blocking policy belongs in pre-commit hooks or tests/ci.

Canonical Pre-PR Flow¶

Run this before opening or updating a PR:

bash .claude/scripts/pre-commit-validation.sh

That command must expand to this canonical command set:

1. pre-commit validate-config
2. pre-commit run --all-files
3. pytest tests/ci -q --no-cov --override-ini="addopts="

Why this split: - pre-commit is the staged-file gate — --all-files ensures local and CI run the same hooks - tests/ci is the semantic gate - the shell script is just the orchestrator

How to Add a New Guardrail¶

Add a new rule to the narrowest layer that can enforce it cleanly:

1. Use .pre-commit-config.yaml for changed-file, grep-like, formatter, lint, or focused test gates.
2. Use tests/ci/ for AST checks, repository-wide assertions, workflow contracts, or docs/code alignment.
3. Update .github/workflows/ci.yml when a CI-only guardrail needs runtime support such as GITHUB_TOKEN or pull-requests: read.
4. Update documentation after the enforcement layer exists, not before.

Do not add new blocking policy directly to .claude/scripts/pre-commit-validation.sh.

API Compatibility Rule Index¶

Issue #813 adds allowlisted public-signature compatibility checks. These are semantic checks and therefore belong in CI tests, not shell-script heuristics.

Implementation detail: - Detector implementation lives in src/file_organizer/review_regressions/api_compat.py. - Deterministic positive/safe proofs live in tests/unit/review_regressions/test_api_compat_detectors.py.

Custom API-Compat Contracts¶

When defining custom allowlists, import from the detector module directly:

from pathlib import Path

from file_organizer.review_regressions.api_compat import (
    PublicApiCompatibilityDetector,
    PublicCallableContract,
)

custom_detector = PublicApiCompatibilityDetector(
    contracts=(
        PublicCallableContract(
            path=Path("src/file_organizer/core/organizer.py"),
            qualname="FileOrganizer.__init__",
            legacy_positional_params=("text_model_config", "vision_model_config"),
        ),
    )
)

Why direct module import: - avoids ambiguity between pack-level exports and detector-specific types - keeps custom-contract code aligned with the detector's canonical module

Memory Lifecycle Rule Index¶

Issue #803 adds buffer/memory lifecycle regression checks. These are semantic invariants and therefore belong in CI tests, not shell-script heuristics.

Implementation detail: - Detector implementation lives in src/file_organizer/review_regressions/memory_lifecycle.py. - Deterministic positive/safe proofs live in tests/unit/review_regressions/test_memory_lifecycle_detectors.py.

Search Guardrail Rule Index¶

Issue #869 adds corpus-safety checks for the search service. These are AST-based semantic checks and therefore belong in CI tests, not shell-script heuristics.

Implementation detail: - Guardrail logic lives in tests/ci/test_search_code_quality.py (function _find_unguarded_traversals). - Detection uses AST call-node matching scoped to each function's own body — docstrings and comments cannot produce false positives. - Rule definitions and fix examples live in .claude/patterns/search-generation-patterns.md patterns S1 and S2.

T10 Predicate Negative-Case Rule Index¶

Issues #930 and #931 add two enforcement layers for the T10 pattern: every _is_*/_has_*/_find_* predicate in detector modules must have a paired negative test case (assert not predicate(...)).

Shared logic lives in .claude/scripts/check_predicate_negative_coverage.py. The CI test imports from this script via importlib; the pre-commit hook runs it directly. Update the script when new detector modules are added.

To add a new detector module: add its entry to _MODULE_TO_TEST in the script, add assert not predicate(...) calls to the test file for every new predicate, then verify pre-commit run predicate-negative-coverage and pytest tests/ci/test_predicate_negative_coverage.py both pass.

CLI Contract Test Conventions¶

Typer and Rich render help text differently across terminals and CI. For CLI contract tests:

• Prefer result.output over result.stdout
• Normalize rendered help before asserting exact content
• Assert semantic fragments unless exact formatting is part of the contract

Example:

result = runner.invoke(app, ["organize", "--help"])
assert result.exit_code == 0
rendered_help = _rendered_text(result.output)
assert "--no-prefetch" in rendered_help

Pitfall: direct assertions on styled help output can pass locally and fail in GitHub Actions because Rich changes wrapping and ANSI rendering.

GitHub-Environment Branching Helpers¶

Guardrail code that branches on GITHUB_* variables is CI-first code. Treat it as such:

• Test both local mode and GitHub PR mode
• Cover the fallback path explicitly
• Avoid assuming a full git history or a specific merge-parent layout
• Prefer GitHub-provided PR context when the question is really about PR files

Examples of CI-only runtime support: - pull-requests: read permission for PR file lookups - GITHUB_TOKEN in workflow steps that call GitHub APIs

Workflow Support Mapping¶

CI workflow configuration is part of the guardrail system, not an incidental detail:

• .github/workflows/ci.yml must expose the permissions and environment needed by CI-only guardrails
• tests/ci/test_workflows.py should lock in those assumptions
• if a guardrail needs workflow support, document the ownership in the same PR

This keeps reviewers from having to infer whether a failure is in the rule itself or in the CI runtime that the rule depends on.