fix(metal): close out motion_v2 mirror reflect-101 parity and test observability

[lusoris]

Summary

Closes out T-METAL-MOTION-V2-MIRROR-OFF-BY-ONE-2026-09-03. The Metal integer_motion_v2 mirror kernel was already corrected to iterated reflect-101 (idx = (idx < 0) ? -idx : 2 * (sup - 1) - idx) in PR #1223 (71da046db), but the file header still described the old 2 * size - idx - 1 fold, docs/state.md and ADR-1166 still recorded the fix as deferred, and the parity test's no-device skip was indistinguishable from a device pass in CI logs. This PR fixes the header comment (comment-only, no kernel change), adds closeout ADR-1176 with a dated Superseded-in-part note on ADR-1166, moves the state.md row to Recently closed, records the cross-twin invariant in core/src/feature/metal/AGENTS.md, and makes test_metal_motion_v2_parity exit 77 (Meson SKIP via mu_skipped = 1) on -ENODEV while printing [metal device active: motion_v2 parity run on device] to stdout on real hardware. Verification on the Linux workstation: all four twins re-read and confirmed reflect-101 (CPU integer_motion_v2.c:157, CUDA motion_v2_score.cu:51, SYCL integer_motion_v2_sycl.cpp:109 dev_mirror_mv2, HIP motion_v2_score.hip:67); git ls-tree origin/master testdata | grep -i metal returns 0 hits so no /regen-snapshots is needed; concat-changelog-fragments.sh --check, concat-adr-index.sh --check, check-copyright.sh, assertion-density.sh (256 asserts / 151 functions, PASS) and pre-commit on all 14 touched files are green. The reviewer corrected the SYCL twin citation from dev_mirror_motion (motion v1) to dev_mirror_mv2 (motion_v2) in the header comment, AGENTS.md, ADR-1176 and the state.md row. Unverified: on-device execution of the parity test on Apple Silicon (no Mac on the workstation) — the Build — macOS Metal CI leg must show either the [metal device active ...] stdout line or a SKIP for this test; zero score movement is expected since no kernel line changes.

Type

• fix — Metal motion_v2 mirror closeout: header comment, docs/state, observable test skip

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (pre-commit on every touched file).
• Unit tests: test_metal_motion_v2_parity now exits 77 (SKIP) on non-Metal hosts and prints a device-active stdout line on Apple Silicon; the macOS CI leg exercises it (no local Mac).
• Docs in the same PR: docs/adr/1176-metal-motion-v2-mirror-closeout.md, docs/adr/README.md, docs/state.md, docs/rebase-notes.md, core/src/feature/metal/AGENTS.md.
• SIMD/GPU, twins, new C sources, breaking change, ADR — GPU: Metal comment-only, kernel unchanged; twins: CPU/CUDA/SYCL/HIP/Metal mv2 mirror confirmed identical; new C sources: n/a; breaking change: n/a; ADR: ADR-1176 (supersedes ADR-1166 in part).

Bug-status hygiene (ADR-0165)

• docs/state.md — T-METAL-MOTION-V2-MIRROR-OFF-BY-ONE-2026-09-03 moved from Open to Recently closed (HTML marker left in Open, closer fix/metal-motion-v2-mirror-closeout).

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: closeout of a fix already researched in docs/research/1166-upstream-issue-harvest-2026-09-03.md; comment/docs/test-exit-code only.
• Decision matrix — docs/adr/1176-metal-motion-v2-mirror-closeout.md §Alternatives considered
• AGENTS.md invariant note — core/src/feature/metal/AGENTS.md (mv2_mirror is reflect-101, identical across backends)
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/metal-motion-v2-mirror-closeout.md
• Rebase note — docs/rebase-notes.md entry (no rebase impact: fork-only Metal backend)

Reproducer

# Kernel is reflect-101 and the header comment now says so (no output = mismatch)
grep -n "2 \* (sup - 1) - idx" core/src/feature/metal/integer_motion_v2.metal
#  20: *  Mirror padding: reflect-101 (`2 * (sup - 1) - idx`, iterated),
#  77:        idx = (idx < 0) ? -idx : 2 * (sup - 1) - idx;
# No Metal snapshot exists, so no /regen-snapshots is needed (expect no output, exit 1)
git ls-tree origin/master testdata | grep -i metal; echo "exit $?"
# Deliverable generators are in sync
bash scripts/release/concat-changelog-fragments.sh --check && bash scripts/docs/concat-adr-index.sh --check && echo OK
# On Apple Silicon (macOS CI leg):
meson test -C core/build test_metal_motion_v2_parity -v
#   stdout: [metal device active: motion_v2 parity run on device]
#   result: OK  (on hosts without a Metal device: SKIP, exit 77)

🤖 Generated with Claude Code