[UC-3697] Establish Quad-Agent architecture, WASM link hygiene, and binding safety

[Jelle Spijker (jellespijker)]

Jira ticket: UC-3697

Why

libUvula is a core geometry library serving dual critical consumers:

1. UltiMaker Digital Factory & Neoprep: WebAssembly (UvulaJS / @ultimaker/uvulajs) executed in browser Web Workers for live 3D viewport paint stroke projections and UV unwrapping.
2. UltiMaker Cura: C++ core and Python bindings (pyUvula) via Conan 2 packages.

To support high-velocity, reliable multi-agent development and resolve build hygiene/memory safety vulnerabilities identified during adversarial red-teaming, this PR establishes the complete Quad-Agent developer environment and hardens the WebAssembly and Python binding interfaces.

---

What

1. Quad-Agent Architecture: Full developer configuration, governance rules, and lifecycle verification hooks for Claude Code, Antigravity, OpenCode, and Copilot.
2. WebAssembly (UvulaJS) & Python (pyUvula) Hardening:
   • Eliminated dead -s FORCE_FILESYSTEM=1 and removed -s ERROR_ON_UNDEFINED_SYMBOLS=0 from Emscripten link options.
   • Added modulo flat array buffer bounds checks and Embind try/catch exception boundary guards in UvulaJS.cpp.
   • Added 2D numpy buffer dimension validation and released Python GIL (py::gil_scoped_release) during intensive viewport projections in pyUvula.cpp.
3. CI/CD Triggers: Enabled automatic package builds on UC-* push branches in .github/workflows/package.yml.
4. Domain Documentation & Parity: Documented UV unwrapping/projection algorithms in AGENTS.md and settled all 9 bootstrap proposals.

---

How

1. WebAssembly Boundary & Memory Safety (UvulaJS/)

• UvulaJS/CMakeLists.txt: Removed virtual filesystem code from in-memory geometry compilation and enforced strict symbol resolution at link time.
• UvulaJS/UvulaJS.cpp:
  • Added % 3 == 0 and % 2 == 0 length guards in Geometry constructor, unwrap(), and project() to protect against buffer over-reads from malformed typed arrays.
  • Wrapped geometry calls in try ... catch blocks returning structured fallbacks to prevent uncaught C++ exceptions from terminating host Web Workers.

2. Python Concurrency & Buffer Validation (pyUvula/)

• pyUvula/pyUvula.cpp:
  • Validates buffer.ndim == 2 for polygon and mesh inputs, and exact sizes (16 for projection matrix, 3 for camera normal).
  • Released the Python GIL during doProject() so heavy mesh projection computations do not block multi-threaded Cura operations.

3. Agentic Lifecycle Hooks & Verification Gates (.agents/hooks/)

• Pre-commit: 20 automated checks including clang-format, Talisman credential scanning, path protection, file-size ratchet (400 lines), cyclomatic complexity budget (10/function), rule numbering integrity, and multi-intent scope check.
• Skill Discovery: Scoped suggestions exclusively to stderr with mappings for ultimaker-neoprep-development, ultimaker-cura-development, cpp-pro, and cmake.

---

Verification & Validation (V&V)

Pre-Commit Quality Gate (20/20 Passed):

check for merge conflicts................................................Passed
check yaml...............................................................Passed
check json...............................................................Passed
check for added large files..............................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
talisman.................................................................Passed
clang-format.............................................................Passed
Block absolute local path references.....................................Passed
Detect hardcoded API keys and credentials................................Passed
Refuse commits on protected branches.....................................Passed
Verify AI exclusion targets match .aiignore..............................Passed
Enforce rule numbering bands, frontmatter coherence and managed-space...Passed
Verify the Copilot rule index lists every rule in .agents/rules..........Passed
Enforce file size budget and grandfathering ratchet......................Passed
Enforce cyclomatic complexity budget on changed code.....................Passed
Verify 100% parity across Quad-Agent configuration targets...............Passed
Prevent disabling pre-commit hooks or Talisman credentials scanning......Passed
Verify alignment with upstream release branches..........................Passed
Detect multi-intent PRs mixing features with refactoring.................Passed

Pre-PR Adversarial Quality Audit:

==> Running Pre-PR Verification & Quality Gate Audit...
[All pre-commit checks passed]
==> Checking orientation docs are actually filled in...
==> Running Adversarial Security, Quality & Intent Audit on 133 modified files...
✅ Adversarial Security, Quality & Intent Audit Passed Cleanly!
==> Verifying credential and environment file isolation...
✅ All verification checks passed cleanly!

---

PR Checklist

• Describe the changes that were made and why
• Initiating developer reviewed AI-generated code
• Pre-commit and adversarial security checks pass cleanly
• Bisect-safe atomic commit history preserved

[Copilot]

Pull request overview

Adds a repository-level pre-commit configuration to enforce basic hygiene checks and introduce secret/path scanning prior to commits, supporting UC-3697 by reducing the chance of committing sensitive data or environment-specific paths.

Changes:

• Introduces .pre-commit-config.yaml configuring standard pre-commit-hooks checks (YAML/JSON validation, whitespace fixes, large-file checks).
• Adds Talisman hook configuration to scan commits for potential secrets, with explicit exclude patterns.
• Adds a local pygrep hook to block absolute local path references (e.g., /home/..., /Users/...) with documented exclusions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Jelle Spijker (jellespijker)]

🛡️ Adversarial Security Audit & Quad-Agent Review Summary

• Adversarial Security Audit: Passed 100% cleanly (run_adversarial_audit.py). Conflict markers cleaned in UvulaJS C++ wrapper.
• Quad-Agent Configuration Parity: 100% verified across Antigravity (.agents/), Claude Code (.claude/), Copilot (.github/), and OpenCode (.opencode/).
• Stack Behavioral Assessment:
  • Modern C++ UV unwrapping engine & WebAssembly/pyUvula bindings.
  • Pre-tool guards enforce path safety and code style compliance.

[HellAholic]

The check causes an exception when called from Cura's paintTool code:
https://github.com/Ultimaker/Cura/blob/5068661cd448b954328483a499fe4ff419b695b5/plugins/PaintTool/PaintTool.py#L369

Exception: Error when adding paint stroke
Invalid array dimensions for projection inputs (expected 2D arrays).

Potentially due to:
https://github.com/Ultimaker/Cura/blob/5068661cd448b954328483a499fe4ff419b695b5/plugins/PaintTool/PaintTool.py#L265-L266

Something like the change below might work, but also requires updating the shape[0] entries for stroke_polygon and the other consts that follow it.

Suggested change

	if (stroke_polygon_buffer.ndim != 2 || mesh_vertices_buffer.ndim != 2 || mesh_indices_buffer.ndim != 2 || mesh_uv_buffer.ndim != 2 || mesh_faces_connectivity_buffer.ndim != 2)
	{
	throw std::runtime_error("Invalid array dimensions for projection inputs (expected 2D arrays).");
	}
	if (stroke_polygon_buffer.size % 2 != 0 || mesh_vertices_buffer.size % 3 != 0 || mesh_indices_buffer.size % 3 != 0 || mesh_uv_buffer.size % 2 != 0 || mesh_faces_connectivity_buffer.size % 3 != 0)
	{
	throw std::runtime_error("Invalid array dimensions for projection inputs (expected 2D arrays).");
	}