fix: converge Python-Rust parity for Copilot hooks

[rysweet]

Summary

Converges the in-progress Python-Rust parity slice into a clean review branch.

What changed

• aggregate Copilot pre-tool-use results from amplihack and XPIA into one permission payload
• make canonical XPIA pre-tool-use Rust-backed and keep pre_tool_use_rust.py as a compatibility shim
• prefer the Rust hook engine automatically when amplihack-hooks is installed
• hand off top-level install, recipe, mode, and update commands to the Rust CLI when available
• reuse the tested nested Copilot normalizer instead of duplicating compatibility logic
• align docs and targeted tests with the parity model

Validation

• PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_main_rust_cli_handoff.py tests/test_rust_hook_engine.py tests/test_rust_xpia.py tests/test_xpia_hook_integration.py tests/test_outside_in_xpia_rust.py tests/outside_in/test_hook_e2e.py tests/gadugi/copilot_nested_compat_smoke.py tests/recipes/test_rust_runner.py tests/recipes/test_rust_runner_support.py tests/recipes/test_rust_runner_recipe_resolution.py tests/unit/recipes/test_recipe_progress_banners.py
  • result: 372 passed, 3 xfailed

Notes

This PR branch was recreated cleanly from main so temporary debug artifacts and unrelated workflow-only changes from the original worktree are not included.

[github-actions]

Repo Guardian - Passed

All 28 changed files in this PR have been reviewed. No ephemeral content was found.

Category	Files	Verdict
Source code (src/amplihack/)	6 files	✅ Durable implementation
Tests (tests/)	10 files	✅ Proper test suite
Hook/command configs (.claude/, .github/)	5 files	✅ Reusable toolchain
Specs/xpia_hook_integration.md	1 file	✅ Formal module spec with contracts
docs/HOOKS_COMPARISON.md	1 file	✅ Technical reference (date header is normal for comparison docs)
docs/features/copilot-installation-reporting.md	1 file	✅ Feature reference doc with use cases and testing guidance
docs/reference/copilot-installation-implementation.md	1 file	✅ Maintainer technical reference
docs/howto/settings-hook-configuration.md	1 file	✅ How-to guide
README.md	1 file	✅ Not ephemeral

No meeting notes, sprint retrospectives, one-off scripts, debug utilities, or point-in-time status documents detected.

Generated by Repo Guardian for issue #3500 · ◷

[github-actions]

Repo Guardian - Passed

All 36 changed files in this PR have been reviewed. No ephemeral content was found.

Category	Files	Verdict
Source code (src/amplihack/)	6 files	✅ Durable implementation
Tests (tests/)	11 files	✅ Proper test suite
Hook/command configs (.claude/, .github/)	5 files	✅ Reusable toolchain
Specs/xpia_hook_integration.md	1 file	✅ Formal module spec with contracts
docs/concepts/copilot-parity-control-plane.md	1 file	✅ Concept/explanation doc (Diataxis) — no ephemeral language
docs/tutorials/copilot-parity-control-plane.md	1 file	✅ Tutorial with step-by-step instructions — durable
docs/reference/copilot-parity-control-plane.md	1 file	✅ Reference doc with contracts and tables — durable
docs/howto/configure-copilot-parity-control-plane.md	1 file	✅ How-to guide — durable
Other modified docs	8 files	✅ Technical reference docs — durable
README.md, mkdocs.yml	2 files	✅ Not ephemeral

No meeting notes, sprint retrospectives, one-off scripts, debug utilities, or point-in-time status documents detected. The last_updated date fields in documentation frontmatter are standard metadata, not ephemeral content.

Generated by Repo Guardian for issue #3500 · ◷

[github-actions]

Repo Guardian - Passed

All 49 changed files in this PR have been reviewed. No ephemeral content was found.

Category	Files	Verdict
Source code (src/amplihack/)	6 files	✅ Durable implementation
Tests (tests/)	11 files + 1 smoke harness	✅ Proper test suite
Hook/command configs (.claude/, .github/)	5 files	✅ Reusable toolchain
Specs/xpia_hook_integration.md	1 file	✅ Formal module spec
docs/atlas/ast-lsp-bindings/*	6 files	✅ Code atlas layer — architectural binding tables refreshed per PR as part of a living documentation system
docs/atlas/service-components/*	6 files	✅ Code atlas layer — same pattern; "PR #3500" references are changelog-style metadata, not ephemeral status
docs/COPILOT_CLI.md	1 file	✅ Feature reference doc with version metadata — durable
docs/howto/use-non-claude-agent.md	1 file	✅ How-to guide — durable
Other modified docs	11 files	✅ Concept, tutorial, reference, and how-to docs — durable
README.md, mkdocs.yml	2 files	✅ Not ephemeral

No meeting notes, sprint retrospectives, one-off scripts, debug utilities, or point-in-time status documents detected.

To override future guardian decisions, add a PR comment containing repo-guardian:override (reason) where (reason) is a required non-empty justification.

Generated by Repo Guardian for issue #3500 · ◷

[github-actions]

🤖 PM Architect PR Triage Analysis

PR: #3500
Title: fix: converge Python-Rust parity for Copilot hooks
Author: @rysweet
Branch: fix/copilot-3336-parity-convergence → main

---

✅ Workflow Compliance (Steps 11-12)

❌ NON-COMPLIANT - PR needs workflow completion

Step 11 (Review): ❌ Incomplete

• Insufficient review evidence. Found 0 formal reviews and 3 comments. Review score: 0 (need >= 5). Comprehensive review detected: False

Step 12 (Feedback): ❌ Incomplete

• Insufficient feedback implementation. Response score: 1 (need >= 3)

Blocking Issues:

• Step 11 incomplete: Need comprehensive code review with security, quality, and philosophy checks
• Step 12 incomplete: Need to address and respond to review feedback

🏷️ Classification

Priority: HIGH

• Bug fix or important change

Complexity: VERY_COMPLEX

• 48 files with 7259 lines changed - system-wide changes (architectural changes detected)

🔍 Change Scope Analysis

⚠️ UNRELATED CHANGES DETECTED

Primary Purpose: Bug fix

Unrelated Changes:

• Documentation changes

Affected Files:

• .claude/commands/amplihack/xpia.md
• .github/commands/xpia.md
• readme.md
• specs/xpia_hook_integration.md
• docs/copilot_cli.md
• docs/hooks_comparison.md
• docs/atlas/ast-lsp-bindings/readme.md
• docs/atlas/ast-lsp-bindings/ast-lsp-bindings-dot.svg
• docs/atlas/ast-lsp-bindings/ast-lsp-bindings-mermaid.svg
• docs/atlas/ast-lsp-bindings/ast-lsp-bindings.dot

Recommendation: Consider splitting this PR into separate focused PRs for each concern

💡 Recommendations

• Complete workflow steps 11-12 before marking PR as ready
• Add at least one formal code review

---

📊 Statistics

• Files Changed: 48
• Comments: 3
• Reviews: 0

---

🤖 Generated by PM Architect automation using Claude Agent SDK

[github-actions]

Repo Guardian - Passed

All 56 changed files in this PR have been reviewed. No ephemeral content was found.

Category	Files	Verdict
Source code (src/amplihack/)	9 files	✅ Durable implementation
Tests (tests/)	13 files	✅ Proper test suite
Hook/command configs (.claude/, .github/)	5 files	✅ Reusable toolchain
Specs/xpia_hook_integration.md	1 file	✅ Formal module spec with contracts
docs/HOOKS_COMPARISON.md	1 file	✅ Durable technical reference — structured API comparison tables, Last Updated is version metadata not ephemerality
docs/features/copilot-installation-reporting.md	1 file	✅ Feature documentation with Before/After examples — describes fixed behavior durably
docs/atlas/ast-lsp-bindings/*, docs/atlas/service-components/*	12 files	✅ Code atlas layers — living architectural diagrams
docs/claude/commands/amplihack/xpia.md	1 file	✅ Command reference doc
tests/gadugi/copilot_nested_compat_smoke.py	1 file	✅ Outside-in smoke harness using amplihack library — not a one-off debug script
Other docs (concepts/, howto/, reference/, tutorials/, troubleshooting/)	10 files	✅ Diataxis-structured reference docs — durable
README.md, mkdocs.yml	2 files	✅ Not ephemeral

No meeting notes, sprint retrospectives, one-off scripts, debug utilities, or point-in-time status documents detected.

To override future guardian decisions, add a PR comment containing repo-guardian:override (reason) where (reason) is a required non-empty justification for allowing the file(s).

Generated by Repo Guardian for issue #3500 · ◷

[github-actions]

PR Triage Report

Classification: Bug Fix / Infrastructure Convergence | Risk: High | Priority: High

Assessment

Dimension	Result
Author	rysweet
Scope	Core hook infrastructure — Copilot hooks, XPIA pre-tool-use, Rust CLI handoff, normalizers
Risk	High — changes default runtime behavior (Rust hook engine auto-preferred, CLI command handoff)
Tests	✅ 372 passed, 3 xfailed
Branch	Recreated cleanly from main (no debug artifacts)
Conflicts	None

Changes (High-Impact)

1. Copilot pre-tool-use aggregation — merges amplihack + XPIA results into single permission payload
2. XPIA pre-tool-use → Rust-backed — pre_tool_use_rust.py becomes compatibility shim
3. Rust hook engine auto-preference — automatically selected when amplihack-hooks installed (behavior change)
4. CLI command handoff — install, recipe, mode, update handed to Rust CLI when available
5. Nested Copilot normalizer reuse — removes duplicated compatibility logic

Risk Factors

• Behavior change: Rust engine is now auto-selected — could surface latent Rust-vs-Python parity gaps in edge cases not covered by tests
• Security-adjacent: XPIA pre-tool-use path is security-critical; Rust-backing must maintain identical semantics
• Cross-cutting: Touches hook selection, CLI dispatch, XPIA, and normalizer — wide blast radius
• Compatibility shim: pre_tool_use_rust.py retained for backwards compat — verify this path is tested

Positive Signals

• 372 tests pass (including test_rust_hook_engine.py, test_rust_xpia.py, test_xpia_hook_integration.py, test_outside_in_xpia_rust.py)
• Branch recreated cleanly from main
• Normalizer reuse reduces duplication (maintenance benefit)

Recommendation

Needs deep review before merge. Reviewers should focus on:

1. Rust hook engine fallback behavior when amplihack-hooks is not installed (regression guard)
2. XPIA semantic parity between Python and Rust paths
3. CLI handoff error handling (what happens when Rust CLI is absent mid-command?)
4. Coverage of the pre_tool_use_rust.py compatibility shim path

Generated by PR Triage Agent · ◷

[github-actions]

Repo Guardian - Passed

All 58 changed files in this PR have been reviewed. No ephemeral content was found.

Category	Files	Verdict
Source code (src/amplihack/)	9 files	✅ Durable implementation
Tests (tests/)	14 files	✅ Proper test suite
Hook/command configs (.claude/, .github/)	5 files	✅ Reusable toolchain
Specs/xpia_hook_integration.md	1 file	✅ Formal module spec with contracts
docs/HOOKS_COMPARISON.md	1 file	✅ Technical reference — structured API comparison tables; Last Updated is version metadata
docs/atlas/ast-lsp-bindings/*, docs/atlas/service-components/*	12 files	✅ Code atlas layers — living architectural diagrams
docs/claude/commands/amplihack/xpia.md, docs/COPILOT_CLI.md	2 files	✅ Command and feature reference docs
docs/concepts/, docs/howto/, docs/reference/, docs/tutorials/, docs/troubleshooting/	11 files	✅ Diataxis-structured reference docs — durable
docs/index.md, README.md, mkdocs.yml	3 files	✅ Not ephemeral

No meeting notes, sprint retrospectives, one-off scripts, debug utilities, or point-in-time status documents detected. The .github/hooks/pre-tool-use bash script is a parameterized, reusable hook wrapper — not a one-off fix script.

To override future guardian decisions, add a PR comment containing repo-guardian:override (reason) where (reason) is a required non-empty justification for allowing the file(s).

Generated by Repo Guardian for issue #3500 · ◷