feat(scripts): add --ci alias for --strict + CI-gate doc updates

scripts/audit_exception_handling.py

@@ -2,8 +2,11 @@
 """Audit try/except/finally/raise usage against the data-oriented error
 handling convention.
 
-This is an INFORMATIONAL audit, not a CI gate. It produces a report that the
-user (or a follow-up track) uses to decide whether a refactor is worth it.
+This audit is INFORMATIONAL by default (exits 0) so developers can run it
+freely to see the current state. Pass `--strict` (or its alias `--ci`)
+to enable CI-gate mode (exits 1 on any violation). The 4-script
+enforcement set (see docs/AGENTS.md "Convention Enforcement") uses
+`--strict` mode for pre-commit hooks and CI.
 
 The convention (see conductor/code_styleguides/error_handling.md) requires:
 
@@ -47,10 +50,17 @@ Usage:
   uv run python scripts/audit_exception_handling.py --src src      # source dir
   uv run python scripts/audit_exception_handling.py --top 20       # top N files
   uv run python scripts/audit_exception_handling.py --verbose       # every site
-  uv run python scripts/audit_exception_handling.py --strict        # exit 1 on violation
+  uv run python scripts/audit_exception_handling.py --strict        # CI gate (exit 1 on violation)
+  uv run python scripts/audit_exception_handling.py --ci            # alias for --strict
   uv run python scripts/audit_exception_handling.py --summary      # per-file summary table
   uv run python scripts/audit_exception_handling.py --by-size       # group by migration effort
 
+Pre-commit / CI use (the convention's CI gate):
+  uv run python scripts/audit_exception_handling.py --strict
+  # Exits 1 on any violation. Use in pre-commit hooks and CI to enforce
+  # the data-oriented error handling convention. Part of the 4-script
+  # enforcement set (see docs/AGENTS.md "Convention Enforcement").
+
 Output modes (mutually exclusive; --json / --summary / --by-size override
 the default human-readable report):
   --summary: per-file table sorted by V+S descending. Use this for
@@ -60,8 +70,9 @@ the default human-readable report):
   (default): top-N files with per-site breakdown and 1-line hints.
 
 Exit codes:
-  0 - audit ran (informational mode; findings don't fail the script)
-  1 - usage error, or --strict mode with violations found
+  0 - audit ran in informational mode (default; no violations fail the script)
+  1 - usage error, or --strict/--ci mode with violations found
+  2 - source directory not found
 """
 from __future__ import annotations
 import argparse
@@ -838,7 +849,8 @@ def main() -> int:
  parser.add_argument("--top", type=int, default=15, help="Show top N files by violation count (default: 15)")
  parser.add_argument("--verbose", action="store_true", help="Show every site inline (default: top N summary)")
  parser.add_argument("--include-tests", action="store_true", help="Also scan tests/ and scripts/")
- parser.add_argument("--strict", action="store_true", help="Exit 1 if any violations are found (for CI use)")
+ parser.add_argument("--strict", action="store_true", help="Exit 1 if any violations are found (for CI use; the convention's CI gate)")
+ parser.add_argument("--ci", dest="strict", action="store_true", help="Alias for --strict (clearer name for CI scripts; e.g., pre-commit hooks)")
  parser.add_argument("--include-baseline", action="store_true", help="Include the 3 refactored files in the violation count (default: exclude)")
  parser.add_argument("--summary", action="store_true", help="Per-file summary table (for migration planning)")
  parser.add_argument("--by-size", action="store_true", help="Group files by migration effort bucket (small/medium/large/baseline)")