Gate configured-handler hook smoke matrix in Required CI

[Chris0Jeky]

Failure-ledger renderer synchronization is now enforced by Required Docs Governance via PR #1493. The remaining gap is narrower: scripts/agent_hooks/smoke_test.py and the exact handlers configured in .claude/settings.json are still not exercised by a hosted required gate.

Why this still matters

The smoke matrix is the executable specification for what the command deny floor must block and must allow. It also invokes the configured handlers, so it can detect configuration drift or a silently unregistered/unlaunchable hook.

Two 2026-07-25 findings show the value of this gate:

• pre_tool_use.py denies benign commands that merely mention a dangerous string (6/8 false positives) #1475: the shipped hook denied six of eight benign commands; a MUST-ALLOW row would have failed at authoring time.
• PR fix(#1293): consolidate deny-floor to global + thin overlay #1295: review found a 13/13 bypass rate against its stated contract even though a larger branch-local smoke suite existed.

Scope

• Use the functional cross-platform launcher contract established by Resolve a functional Python launcher for Windows agent utilities #1487; do not add a second resolver.
• Run scripts/agent_hooks/smoke_test.py in Required CI against the checked-out .claude/settings.json.
• Preserve coverage of both MUST-ALLOW and MUST-DENY command shapes and exact configured-handler invocation.
• Make handler removal, registration drift, or launch failure fail the required gate.
• Keep Windows-specific command shapes covered even if part of the matrix runs on another host.
• Document the local equivalent command and the hosted runner assumptions.

Acceptance criteria

• A clean exact-head run proves the configured-handler smoke matrix passes in Required CI.
• A controlled mutation to handler registration or an allow/deny expectation is rejected.
• Existing failure-ledger synchronization coverage remains intact.
• docs/STATUS.md, docs/IMPLEMENTATION_MASTERPLAN.md, and test guidance reflect the delivered gate.
• Exact-head CI, CI Extended, review, and comment-triage gates pass before merge.

This remains substrate work and should land before further deny-floor expansion under #1293.

Provenance

Originally surfaced by the #1295 salvage assessment on 2026-07-25. Scope narrowed on 2026-07-26 after PR #1493 added Required-CI coverage for the failure-ledger renderer while leaving the configured-handler smoke matrix ungated.