fix: restore AI CLI helpers and align mypy pre-push gate

[lusoris]

Summary

Fixes the fail-closed pre-push mypy delta gate so branch and merge-base sources
are evaluated under the same checker configuration, with canonical module
identity and blocker-status handling. It also restores the accepted
ADR-0680/0681 shared bootstrap, parser, and replay-argv contract across twelve
current tiny-AI evaluation, quantization, and export scripts, guarded by an AST
red-cap and direct-file/module probes.

This closes
T-CI-MYPY-PREPUSH-BASELINE-USES-BASE-CONFIG-2026-09-21 and the BUG-048
AI-CLI helper cluster. BUG-048 itself remains open for its other independent
restoration sections.

Commit d170ef86a silently replaced the already-accepted shared CLI/bootstrap
helpers with hand-rolled path, parser, and argv handling. This PR selectively
restores ADR-0680/0681 behavior while preserving every later functional CLI
and provenance change; it does not roll back the training scaffold.

Type

• fix — bug fix
• build / ci — tooling / infra
• feat — new feature
• perf — performance improvement
• refactor — no behavior change
• docs — documentation only
• test — test-only
• port — cherry-pick from upstream Netflix/vmaf
• sycl / cuda / simd — backend-specific

Checklist

• All commits follow Conventional Commits and carry verified signatures.
• Black, Ruff, changed-file pre-commit, HISS, make verify-all, and the
  normal pre-push gates are green.
• Mypy hook contract tests pass: 32/32.
• Exact focused AI reviewer set passes: 46/46.
• Complete ai/ package passes: 1,327 passed, 1 skipped.
• All 29 scanner-visible touched files are clean.
• No SIMD/GPU code path, feature extractor, or native file was changed.
• This is not a breaking change.

Bug-status hygiene

• docs/state.md closes both scoped rows with executable evidence and
  explicitly keeps the wider BUG-048 restoration effort open.

Netflix golden-data gate

• No Netflix golden assertion or test data was modified.
• No golden-value exception is requested.

Local validation

Mypy gate repair

• python3 scripts/git-hooks/test-pre-push-mypy.py: 32 passed
• Real post-stack pre-push mypy gate: 0 introduced, 601 inherited
• Configuration/blocker regressions: 13 focused cases green

AI CLI/bootstrap restoration

• Semantic restoration red-cap: 12 passed
• Focused helper/provenance/QAT/PTQ/exporter set: 46 passed
• Python 3.14-safe dynamic loader contract: 12 passed
• Direct-file plus python -m --help: 24/24 passed
• Complete ai/ package: 1,327 passed, 1 skipped
• Black 26.5.1 and Ruff 0.16.8: clean

Repository gates

• make verify-all: passed, HISS 264 within the 276 baseline and all 29
  scanner-visible touched files clean
• Normal pre-push gates: passed, including strict MkDocs, security, HISS,
  dedupe, formatting, mypy, and PR-body governance
• Writable AGY normal-mode review found and fixed seven introduced mypy
  findings before publication

Deep-dive deliverables

• Research digest —
  docs/research/2092-mypy-pre-push-config-baseline.md and
  docs/research/2088-bug048-ai-cli-helper-restoration.md.
• Decision matrix — both digests document the only-way correctness
  repairs and rejected suppression, whole-commit replay, and global
  bootstrap-widening alternatives.
• AGENTS.md invariant note — scripts/AGENTS.md pins checker config,
  scope, canonical module identity, and fail-closed status handling;
  ai/AGENTS.md pins the twelve-script helper and Python 3.14 loader contracts.
• Reproducer / smoke-test command — pasted below under Reproducer.
• CHANGELOG fragment —
  changelog.d/fixed/pre-push-mypy-config-baseline.md and
  changelog.d/fixed/bug048-ai-cli-helper-restoration.md.
• Rebase note — docs/rebase-notes.md records both invariant groups.

Reproducer

python3 scripts/git-hooks/test-pre-push-mypy.py
PRE_COMMIT_TO_REF="$(git rev-parse HEAD)" python3 scripts/git-hooks/pre-push-mypy.py
python3 -m pytest \
  ai/tests/test_ai_cli_helper_restoration.py \
  ai/tests/test_eval_report_run_provenance.py \
  ai/tests/test_legacy_eval_report_run_provenance.py \
  ai/tests/test_qat_smoke.py \
  ai/tests/test_ptq_scripts.py \
  ai/tests/test_ptq_cli_contracts.py \
  ai/tests/test_measure_quant_drop_per_ep.py \
  ai/tests/test_dnn_exporter_run_provenance.py -q

Expected: 32 hook tests, no branch-introduced mypy findings, and 46 affected AI
tests pass.

Known follow-ups

• The separate hosted Python Lint job remains advisory and lacks a pinned
  dependency-rich type-check environment; that existing item remains tracked
  as T-CI-MYPY-JOB-CHECKS-NO-FILES-2026-09-21.
• BUG-048 remains open for its other independently reviewed restoration chunks.
• Benchmarking, performance tuning, model work, and retraining remain out of
  scope until correctness and security cleanup completes.
• Integration receipt: stacked PR fix(ai): restore shared CLI helper contracts #1553 was ordinarily squash-merged into this
  branch as commit 862e1b08d; no admin bypass was used.