WRK-0009 — Local native installer verification, 2026-11-16

Changes:
- scripts/install-native.sh: executable Bash 3 compatible installer, Linux x64/ARM64
  and macOS Apple Silicon, environment/pinned GraalVM selection and SDKMAN bootstrap,
  compiler/header/linker preflight, explicit Gradle JDK, staged executable check,
  independent copy plus relative aie link, custom --bin-dir and PATH instructions.
- scripts/test-install-native.py: 14 offline process tests using disposable homes.
- README.md: installation, updating, prerequisites, destinations, architecture limit.
- .github/workflows/build.yml: installer fixtures run in native Linux/macOS jobs.

Commands and observed results:
- bash -n scripts/install-native.sh: exit 0.
- python3 scripts/test-install-native.py: 14 tests passed on final files (12.236s).
  Includes Linux x64/ARM64, macOS ARM64, unsupported platforms, compiler failures,
  SDKMAN bootstrap, JDK selection, custom paths with spaces, build/binary failures,
  preservation of previous installations, symlink replacement, independent copy,
  directory conflicts, help and argument validation.
- ./scripts/install-native.sh --bin-dir /tmp/aie-native-install-verification/bin:
  real GraalVM CE JDK 25.0.5.0.3 / macOS ARM64; native build successful in 1m23s.
  Initial run was interrupted at installation because the script was edited while
  Bash was executing it; final unchanged script rerun completed in full (exit 0),
  reusing the build (Gradle BUILD SUCCESSFUL in 4s), and installed the binary and aie.
- /tmp/aie-native-install-verification/bin/aie --version:
  ai-engineering 0.1.0, exit 0.
- SHA-256 of build/native/nativeCompile/ai-engineering and installed copy matched:
  331633bb1fb9176f8b02c65fba62d423701afac0487147e7b60760a9bb2961ba
- SHA-256 of final scripts/install-native.sh:
  c64966f6e6a72bbc062d70dbebb9e0f8f0db8fbc1d7e3c479ce3e30ff6a66a25
- git diff --check: exit 0.
- bash scripts/native-smoke.sh /tmp/aie-native-install-verification/bin/ai-engineering:
  exit 0. All existing native smoke sections passed using the installed copy:
  DF import, simple project, hexadecimal IDs, refinement, local-CLI fixtures,
  EPIC coordination, multiple repositories, operational cycle and Plan consolidation.
  Exercises processes with no JVM or installed tools in PATH.

Limits:
- Real Linux compilation was not run locally; Linux installation paths exercised
  with fixtures and added to existing Linux CI. The real host is macOS ARM64.
- SDKMAN bootstrap tested with controlled offline fixtures, not a live download.
- No install into the user's ~/.local/bin or system package installation was needed
  for validation. Gradle cache access required sandbox escalation and was approved.
- Build emitted existing deprecation and SLF4J warnings; build configuration was not
  changed as part of this installer task.
- macOS Intel remains excluded because the project's pinned GraalVM lacks support;
  see existing docs/roadmap.md and CI matrix. JVM usage remains documented.

External primary references consulted for implementation:
https://sdkman.io/install/ (ci=true, rcupdate=false bootstrap options)
https://sdkman.io/usage/ (specific-version install and default-version prompt)
https://www.graalvm.org/jdk25/reference-manual/native-image/ (native prerequisites)
