hcie-rust-v3.05/.kilo/plans/v4-commit-regression-gate.md

V4 commit-gated semantic and functional regression mechanism

Objective

Port the v3 commit-gated regression behavior to hcie-rust-v4 so changes are checked before commit and audited after commit, while adding deterministic functional/visual regression tests that catch pixel/API regressions automatically.

v3 logic found

• hcie-rust-v3/.git/hooks/pre-commit
  • Collects staged files with git diff --cached --name-only.
  • Calls .git/hooks/semantic_analyzer.py.
  • If a high-risk module changes, runs cargo test --all-features.
  • Fails the commit on analyzer/test failure.
• hcie-rust-v3/.git/hooks/post-commit
  • Runs logs/generate_semantic_report.py --mode last.
  • Prints and saves a semantic impact report.
  • Does not block the completed commit.
• hcie-rust-v3/logs/generate_semantic_report.py
  • Layer 1: builds Cargo dependency graph and blast radius.
  • Layer 2: analyzes public API diff changes.
  • Layer 3: optional cargo-semver-checks.
  • Exits 1 when highest risk is HIGH.
• hcie-rust-v3/src-tauri/src/visual_regression.rs
  • Golden hash harness using deterministic Engine output.
  • Draws canonical vector shapes, hashes composite pixels, compares against golden SHA-256 values.
  • Exposes Tauri commands for manual regeneration.

v4 current state

• hcie-rust-v4/.git/hooks/pre-commit exists but is disabled with exit 0.
• hcie-rust-v4/.git/hooks/post-commit already runs logs/generate_semantic_report.py --mode last --save.
• hcie-rust-v4/logs/semantic_check.sh already wraps logs/generate_semantic_report.py.
• hcie-rust-v4/logs/generate_semantic_report.py is already v4-aware and uses correct workspace paths.
• hcie-rust-v4/.githooks/generate_semantic_report.py appears stale/v3-oriented and duplicates functionality.
• hcie-rust-v4/project_manifest.json exists but is incomplete for the full v4 workspace.
• Existing tests are present in engine crates and GUI tests, but there is no v4 equivalent of v3's golden visual regression harness.
• Current working tree already has unrelated changes: build.id, lock.sh, unlock.sh, deleted notlat.txt, and untracked _images/. Do not touch these.

Implementation plan

1. Enable v4 pre-commit gate

File: .git/hooks/pre-commit

Behavior:

• Exit immediately if there are no staged files.
• Run logs/semantic_check.sh precommit.
• If semantic analysis fails, block commit.
• If semantic analysis passes, run functional regression gate.
• Keep output concise and actionable.
• Do not stage/unstage files and do not modify the working tree.

Important: .git/hooks is local and not versioned. For repository-level portability, keep the same commands available through tracked logs/* scripts and optionally add a later hook-install script in a separate phase.

2. Strengthen post-commit audit

File: .git/hooks/post-commit

Behavior:

• Run semantic audit with logs/semantic_check.sh audit --save.
• Run post-commit functional regression gate in non-blocking mode.
• Never fail the completed commit; write failures to logs/functional_regression_report.txt or similar.
• Tee human-readable output to terminal.

3. Add functional regression gate script

File: logs/functional_regression_check.sh

Purpose:

• Central runner for functional/visual regression checks used by both hooks and manual CI commands.

Modes:

• --fast: run only core deterministic regression tests.
• --visual: run golden visual regression test only.
• --all: run core engine regression tests plus GUI engine integration tests.
• --affected: run tests for crates affected by staged or last-commit changes.
• --post-commit: non-blocking mode that writes report files and exits 0.

Default behavior:

• If a high-risk crate is touched, run the core regression set.
• If only low-risk files are touched, run the smallest relevant crate test set.
• If no changed files are found, exit 0.

Core regression set:

• cargo test -p hcie-engine-api --test visual_regression
• cargo test -p hcie-draw
• cargo test -p hcie-composite
• cargo test -p hcie-filter
• cargo test -p hcie-brush-engine
• cargo test -p hcie-blend
• cargo test -p hcie-color
• cargo test -p hcie-egui-app/crates/hcie-gui-egui --test canvas_engine engine_composite_after_draw

Affected crate mapping:

• hcie-protocol → run protocol plus all dependent core crates.
• hcie-engine-api → run engine visual regression plus GUI engine integration.
• hcie-egui-app/crates/hcie-gui-egui/src/* → run GUI integration tests.
• hcie-filter/* → run filter tests plus engine visual regression if filter output is involved.
• hcie-draw/*, hcie-composite/*, hcie-blend/*, hcie-color/*, hcie-brush-engine/*, hcie-vector/*, hcie-fx/* → run corresponding crate tests plus engine visual regression.

4. Add v4 golden visual regression harness

File: hcie-engine-api/tests/visual_regression.rs

Purpose:

• Port v3's deterministic golden hash concept to v4 through the public Engine API boundary.
• Keep GUI out of internal engine crates and avoid direct protocol access from GUI.

Design:

• Use hcie_engine_api::Engine only.
• Create deterministic canvases, layers, colors, vector shapes, brush strokes, filters, and undo/redo operations.
• Hash engine.get_composite_pixels() with SHA-256.
• Compare against inline golden hashes.
• Provide HCIE_REGEN_GOLDENS=1 cargo test -p hcie-engine-api --test visual_regression -- --nocapture to print new hashes after manual visual verification.

Initial golden cases:

• white_canvas_empty_document: validates blank document/composite baseline.
• green_rect_draw_and_composite: validates draw_filled_rect_rgba.
• red_rect_over_green_rect: validates layer compositing order.
• vector_rect_golden: validates vector rendering through Engine API.
• brush_stroke_golden: validates brush engine + draw pipeline.
• invert_filter_golden: validates filter pipeline and deterministic output.
• undo_after_rect_golden: validates history snapshot and restoration.

Dependency:

• Add sha2 = "0.10" as a dev-dependency in hcie-engine-api/Cargo.toml.

5. Keep v4 semantic analyzer aligned

Do not replace the existing logs/generate_semantic_report.py unless necessary.

If editing is needed, keep changes minimal:

• Ensure --mode staged and --mode last work with current v4 workspace paths.
• Ensure high-risk detection is conservative for hcie-engine-api, hcie-protocol, hcie-document, hcie-composite, hcie-draw, hcie-blend, hcie-color, hcie-filter, hcie-brush-engine, hcie-vector, hcie-fx, and GUI engine-facing crates.
• Do not run cargo-semver-checks by default because it requires extra tooling and can be slow.

6. Optional follow-up phase

Only if the first phase is complete and the user wants repository-portable hooks:

• Add a tracked hook installer such as tools/install-git-hooks.sh.
• Optionally clean up duplicate .githooks/generate_semantic_report.py or make it delegate to logs/generate_semantic_report.py.
• Document manual commands in an existing project note only if requested.

Validation plan

After implementation, run:

1. Semantic precommit gate:

   • bash logs/semantic_check.sh precommit

2. Functional fast gate:

   • bash logs/functional_regression_check.sh --fast

3. Golden visual regression:

   • cargo test -p hcie-engine-api --test visual_regression

4. GUI engine integration:

   • cargo test -p hcie-egui-app/crates/hcie-gui-egui --test canvas_engine

5. Hook smoke checks without committing:

   • bash .git/hooks/pre-commit
   • bash .git/hooks/post-commit

Expected outcome:

• Pre-commit blocks only when semantic risk is HIGH or regression tests fail.
• Post-commit always completes and writes reports.
• Functional regressions fail deterministically when public Engine output changes unexpectedly.