Add riscv64-clang Makefile target; closes out 2026-07-24 punch list

Resolves item #3 of docs/working/archive/session-logs/2026-07-24-punch-list.md
("riscv64 hosted build isn't reachable via plain make"), the last open
item from that list. Decided against options (b) chasing GCC's riscv64
nanosleep-visibility failure at its root (undiagnosed, open-ended) and
(c) leaving it manual — instead wired the already-verified clang recipe
(commit 4485c38 / e287334) into the Makefile, mirroring the existing
rpi4-cross pattern.

Makefile: new riscv64-clang target. CFLAGS deliberately does not reuse
$(BASE_CFLAGS) (hardcodes -std=c99); clang needs -std=c11 -pthread here
instead. Registered in `make help` and .PHONY.

docs/lithosananke/hosted-acceptance-test/README.md: riscv64 section now
points at `make riscv64-clang` instead of the long manual invocation.
Updated Background section and commit list to reflect that all three
punch-list items touching this doc (#1 asm fix, #2 doc command, #3 make
target) are now resolved.

Verified: `make riscv64-clang` produces a binary with identical results
to the manual command it replaces (965 passed / 0 failed, "ALL
IMPLEMENTED TESTS PASSED!", "3 Goodbye!" for the piped acceptance script).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Makefile

@@ -475,7 +475,7 @@ CONFDIR = $(PREFIX)/etc/starforth
 
 .PHONY: all banner help clean clean-obj clean-docs starkernel mkcapsule capsule-gen capsule-manifest
 .PHONY: fastest fast turbo
-.PHONY: rpi4 rpi4-cross rpi4-fastest
+.PHONY: rpi4 rpi4-cross rpi4-fastest riscv64-clang
 .PHONY: minimal debug profile performance
 .PHONY: test bench benchmark
 .PHONY: asm sbom
@@ -562,6 +562,23 @@ rpi4-fastest:
 	        all
 	@echo "✓ Raspberry Pi FASTEST build ready: $(call binary_path,fastest,raspi)"
 
+# RISC-V 64 - cross-compile via clang (GCC fails to build this tree under
+# -std=c99: a nanosleep visibility failure, not yet root-caused — see
+# docs/lithosananke/hosted-acceptance-test/README.md and
+# docs/working/archive/session-logs/2026-07-24-punch-list.md item #3).
+# CFLAGS deliberately does NOT reuse $(BASE_CFLAGS): BASE_CFLAGS hardcodes
+# -std=c99, and clang needs -std=c11 -pthread here. This mirrors the exact
+# recipe verified in the hosted-acceptance-test doc, kept in sync with it.
+riscv64-clang:
+	@echo "🦀 Cross-compiling for RISC-V 64 (clang)..."
+	@$(MAKE) ARCH=riscv64 TARGET=fastest \
+	        CC="clang-18 --target=riscv64-linux-gnu --sysroot=/usr/riscv64-linux-gnu" \
+	        CFLAGS="-std=c11 -pthread -Wall -Werror -Iinclude -Isrc/word_source -Isrc/test_runner/include -DSTRICT_PTR=1 -march=rv64gc -mabi=lp64d -mcmodel=medany -DARCH_RISCV64=1 -O3 -DUSE_ASM_OPT=1 -DUSE_DIRECT_THREADING=1 -DNDEBUG -flto -static" \
+	        LDFLAGS="-flto -s -static -fuse-ld=lld" \
+	        all
+	@echo "✓ Cross-compiled binary ready: $(call binary_path,fastest,riscv64)"
+	@echo "  Run: qemu-riscv64 $(call binary_path,fastest,riscv64)"
+
 # Minimal/embedded build
 minimal:
 	$(MAKE) MINIMAL=1
@@ -1267,6 +1284,7 @@ help:
 	@echo "  rpi4            - Native build on Raspberry Pi 4"
 	@echo "  rpi4-cross      - Cross-compile from x86_64"
 	@echo "  rpi4-fastest    - Maximum optimization for RPi4"
+	@echo "  riscv64-clang   - Cross-compile for RISC-V 64 via clang (GCC fails here)"
 	@echo "  minimal         - Minimal/embedded build"
 	@echo ""
 	@echo "🔧 DEBUG & DEVELOPMENT:"
@@ -1322,6 +1340,7 @@ help:
 	@echo "📋 EXAMPLES:"
 	@echo "  make fastest                    # Fastest build for current platform"
 	@echo "  make rpi4-cross                 # Cross-compile for Raspberry Pi 4"
+	@echo "  make riscv64-clang              # Cross-compile for RISC-V 64 (clang)"
 	@echo "  make asm                        # Generate assembly for inspection"
 	@echo "  make debug                      # Debug build"
 	@echo "  make PREFIX=/usr/local install  # Install system-wide"

docs/lithosananke/hosted-acceptance-test/README.md

@@ -2,7 +2,9 @@
 
 **Date**: 2026-07-24 (original), corrected 2026-08-02
 **Branch**: `master`
-**Commits**: `edced063` (original block-subsystem fix), this correction pass
+**Commits**: `edced063` (original block-subsystem fix), `4485c38` (doc +
+3 clang-surfaced bug fixes), `e287334` (asm register-reuse fix), this pass
+(`riscv64-clang` Makefile target)
 
 ---
 
@@ -86,25 +88,22 @@ directly with no sysroot.
 
 ## riscv64 — cross-compile + QEMU user-mode
 
-There is no dedicated `make` target for this yet (unlike `rpi4-cross` for
-aarch64) — invoke the cross-compile directly. **This leg must use clang,
-not GCC**: `riscv64-linux-gnu-gcc` fails to build this tree (`nanosleep`
-visibility failure under `-std=c99`, unrelated to any project change).
-
 ```bash
-make ARCH=riscv64 \
+make riscv64-clang
-    CC="clang-18 --target=riscv64-linux-gnu --sysroot=/usr/riscv64-linux-gnu" \
-    TARGET=fastest \
-    CFLAGS="-std=c11 -pthread -Wall -Werror -Iinclude -Isrc/word_source -Isrc/test_runner/include -DSTRICT_PTR=1 -march=rv64gc -mabi=lp64d -mcmodel=medany -DARCH_RISCV64=1 -O3 -DUSE_ASM_OPT=1 -DUSE_DIRECT_THREADING=1 -DNDEBUG -flto -static" \
-    LDFLAGS="-flto -s -static -fuse-ld=lld" \
-    all
-
 echo "1 2 + . BYE" | qemu-riscv64 ./build/riscv64/fastest/starforth -s
 ```
 
-Note `-fuse-ld=lld` lives in `LDFLAGS`, not folded into `CC` — clang
+`make riscv64-clang` cross-compiles with `clang-18` (`ARCH=riscv64`,
-rejects it as an unused argument during `-c` (compile-only) invocations
+`TARGET=fastest`, `-static`); see `Makefile:566-579`. **This leg must use
-under `-Werror`.
+clang, not GCC**: `riscv64-linux-gnu-gcc` fails to build this tree
+(`nanosleep` visibility failure under `-std=c99`, unrelated to any project
+change — root cause not yet chased down, see
+`docs/working/archive/session-logs/2026-07-24-punch-list.md` item #3). The
+target's `CFLAGS` deliberately does not reuse the Makefile's
+`$(BASE_CFLAGS)` (which hardcodes `-std=c99`) — clang needs `-std=c11
+-pthread` here instead, plus `-fuse-ld=lld` in `LDFLAGS` (folding it into
+`CC` makes clang reject it as an unused argument during `-c`/compile-only
+invocations under `-Werror`).
 
 ---
 
@@ -166,7 +165,14 @@ The punch list's highest-priority item — a genuine SIGSEGV-causing
 register-reuse hazard in `include/vm_asm_opt_riscv64.h`'s `vm_pop_asm`/
 `vm_rpop_asm` (clang's register allocator can pick the same register for a
 memory operand referenced both before and after a write-back, corrupting
-the result; GCC happens not to hit it) — is a separate, not-yet-ported fix
+the result; GCC happens not to hit it) was *not* required just to get this
-and is **not** required just to get this acceptance test's `-O3` build to
+acceptance test's `-O3` build to compile and pass, but has since been
-compile and pass; it's a latent runtime risk specifically under clang,
+fixed too (commit `e287334`) — and turned out not to be merely a latent
-tracked separately, not resolved by this correction.
+risk: it was silently corrupting 10 `CASE.*` control-flow tests under this
+exact build (`955`/`10 failed` → `965`/`0 failed`, `ALL IMPLEMENTED TESTS
+PASSED!`, with nothing else changed).
+
+Item #3 of the same punch list — no `make` target for this leg, only the
+long manual invocation — is also resolved as of this pass: `make
+riscv64-clang` wires in the same recipe verified above directly into the
+Makefile.