From b5bc22d61ef512e4cc4f94b247e02bf41da455ae Mon Sep 17 00:00:00 2001 From: "Shota Kudo (chaploud)" Date: Tue, 28 Jul 2026 23:34:00 +0900 Subject: [PATCH 1/2] docs(debt): D-526 external-contributor reproducibility / doc-staleness sweep Fresh-clone onboarding audit (prompted by ClojureWasm Discussion #11): build, test, and the 3-OS GitHub CI gate reproduce cleanly with zero host setup; the gaps are maintainer-only tooling + doc staleness (undocumented wasm-tools prereq for test-all, zwasm_from_scratch refs, stale continue/SKILL.md body under its RETIRED banner, drifted check_three_host_diff totals, no Japanese-chat opt-out note). Recorded with a fair WORKS list. Companion: ClojureWasm D-565. Handover pointer added. --- .dev/debt.yaml | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ .dev/handover.md | 6 +++++ 2 files changed, 64 insertions(+) diff --git a/.dev/debt.yaml b/.dev/debt.yaml index d8eb5bbe2..c583c308d 100644 --- a/.dev/debt.yaml +++ b/.dev/debt.yaml @@ -3,6 +3,64 @@ # Refresh on every /continue resume — .claude/skills/continue/RESUME.md Step 0.5. entries: + - id: "D-526" + layer: "docs" + status: "note" + front: D-onboarding + description: |- + External-contributor reproducibility audit (2026-07-28, prompted by + ClojureWasm Discussion #11). A stranger's `git clone` builds, tests, and + gets full 3-OS CI gating with ZERO host-specific setup; everything that + "breaks" is maintainer-only tooling that is env-overridable, gracefully + SKIP/WARN-ing, or explicitly optional. The real liability is DOC STALENESS. + Gaps: + (1) [prereq, undocumented] `zig build test-all` needs `wasm-tools` at build + time (builds spectest.wasm) but README/CONTRIBUTING imply "just Zig"; + only `zig build test` is truly toolchain-free. Add wasm-tools (+ optional + wasmtime) to README install notes with the `.github/versions.lock` pins + (wasm-tools 1.251.0, wasmtime 45.0.0). + (2) [staleness] `.claude/CLAUDE.md` points reference clones at a non-existent + `ClojureWasmFromScratch/` + `~/zwasm/private/…`; the real downstream + consumer is `~/Documents/MyProducts/ClojureWasm/` (correct in + `.dev/reference_clones.md`). Reconcile. + (3) [staleness] retired working-dir `~/Documents/MyProducts/zwasm_from_scratch/` + still cited in `.dev/ROADMAP.md`, `continue/GATE.md`, `STOP_BUCKETS.md` + though README/CLAUDE say it was unified into `zwasm/`. Sweep. + (4) [staleness] `continue/SKILL.md` BODY (Steps 6-8 self-re-arm, + ScheduleWakeup, "loop never voluntarily exits", "fully AUTONOMOUS + campaigns") reads as a live campaign under a "RETIRED" banner. Add + per-section MAINTENANCE markers or archive the sub-docs (audit_scaffolding + skill owns this class). + (5) [staleness] `scripts/check_three_host_diff.sh` hardcodes drifted pass + totals (e.g. 212 passed, 44/55) vs current 56-fixture reality (handover). + Re-anchor or derive. + (6) [onboarding] forced-Japanese chat (settings.json outputStyle + + output_styles/japanese.md) has no outsider-facing "how to disable" note + (code/commits/docs are all English — only chat is affected). + (7) [reproducibility] `spec_revendor_runbook.md` hardcodes `~/Documents/OSS/…` + in copy-paste commands even though the scripts accept WASM_SPEC_REPO / + WASM_TESTSUITE_REPO / WASMTIME_REPO / WASM_PROPOSAL_ROOT overrides — + align the runbook to the env vars, and note the reference clones are + absent even locally (spec re-vendor is maintainer-only; the baked corpora + under test/spec/ ship in the clone). + (8) [cleanup] `scripts/win64_debug/attach_dump.sh` + + `.claude/skills/debug_jit_auto/RECIPES.md` hardcode literal + `Documents/MyProducts/zwasm` / `/c/Users/shota/…` with no override. + WORKS (fair): Zig 0.16.0 pinned coherently (flake.nix / versions.lock / + README); `zig build test` toolchain-free, `test-all` needs only wasm-tools; + committed spec corpus + realworld fixtures run with NO external clone; git + hooks are `git rev-parse`-relative + auto-activated by the flake shellHook; + `.github/workflows/ci.yml` runs the SAME `ci_gate.sh` on mac/linux/windows + runners with no maintainer hardware (a fork PR gets full 3-OS gating — the + strongest reproducibility story); Homebrew tap + prebuilt releases for end + users; the SSH 3-host farm is WARN-and-continue (never hard-fails) and + downgraded to optional pre-PR pre-flight (CI's ci-required is authoritative). + first_raised: "2026-07-28" + last_reviewed: "2026-07-28" + refs: |- + ClojureWasm Discussion #11 (dev-process Q from ieugen); companion ClojureWasm + debt D-565 (same audit, other repo). audit_scaffolding skill owns the + staleness class. - id: "D-523" layer: "test" status: "note" diff --git a/.dev/handover.md b/.dev/handover.md index a5157c794..ea62f7c4b 100644 --- a/.dev/handover.md +++ b/.dev/handover.md @@ -96,6 +96,12 @@ Report = `.dev/meta_audits/2026-07-06-senior-runtime-gap-analysis.md`. - **validator.zig at 3392/3510** — next validator edit extracts per the marker plan first. - D-305 long-tail (niche CM shapes; `component_graph.zig` 1895/2000 split first); D-464 async adversarial; D-462 feature-separation (user-gated). blocked-by rows = parked. +- **D-526** — external-contributor reproducibility / doc-staleness sweep + (fresh-clone onboarding audit, ClojureWasm Discussion #11). Build/test + the + 3-OS GitHub CI gate reproduce cleanly with zero host setup; gaps are undocumented + `wasm-tools` prereq for `test-all` + doc rot (`zwasm_from_scratch` refs, stale + `continue/SKILL.md` body under its RETIRED banner, drifted `check_three_host_diff` + totals) + no Japanese-chat opt-out note. Companion: ClojureWasm D-565. ## State (release = USER-ONLY, ADR-0156) From 5970ee984039137d082f2597e450f18fa9689e04 Mon Sep 17 00:00:00 2001 From: "Shota Kudo (chaploud)" Date: Wed, 29 Jul 2026 00:05:21 +0900 Subject: [PATCH 2/2] chore(config): collapse forced-Japanese chat to outputStyle only The `Japanese` output style (outputStyle in settings.json) is sufficient on its own; the SessionStart hook already injects no language directive. The CLAUDE.md language policy dropped the "+ SessionStart hook" enforcement framing and now documents the single setting + the settings.local.json per-machine override (clean English opt-out). D-526 item (6) discharged. --- .claude/CLAUDE.md | 8 +++++--- .dev/debt.yaml | 7 ++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 98a003dbf..faa275ee3 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -46,9 +46,11 @@ paths. Pre-redesign investigation: `~/zwasm/private/v2-investigation/`. Public project. **English by default** for code, comments, identifiers, commit messages, README, ROADMAP, ADRs, `.dev/`, `.claude/`, all config. -**Japanese** for chat replies only. Enforced by -[`.claude/output_styles/japanese.md`](output_styles/japanese.md) -+ SessionStart hook. +**Japanese** for chat replies only — set by the `Japanese` output style +([`.claude/output_styles/japanese.md`](output_styles/japanese.md), via +`outputStyle` in `settings.json`). That single setting is sufficient; the +SessionStart hook injects no language directive. To work in another +language, override `outputStyle` per-machine in `settings.local.json`. **Bilingual exception**: meta-prose pointers ("詳細は を参照。") and culturally-loaded one-word labels (例: 気付いたら即追加, 裏取り) diff --git a/.dev/debt.yaml b/.dev/debt.yaml index c583c308d..22f7b2ffc 100644 --- a/.dev/debt.yaml +++ b/.dev/debt.yaml @@ -34,9 +34,10 @@ entries: (5) [staleness] `scripts/check_three_host_diff.sh` hardcodes drifted pass totals (e.g. 212 passed, 44/55) vs current 56-fixture reality (handover). Re-anchor or derive. - (6) [onboarding] forced-Japanese chat (settings.json outputStyle + - output_styles/japanese.md) has no outsider-facing "how to disable" note - (code/commits/docs are all English — only chat is affected). + (6) [onboarding] forced-Japanese chat FIXED 2026-07-29 — the CLAUDE.md + language policy now documents overriding `outputStyle` in + settings.local.json (the SessionStart hook injects no language directive; + code/commits/docs are English anyway). (7) [reproducibility] `spec_revendor_runbook.md` hardcodes `~/Documents/OSS/…` in copy-paste commands even though the scripts accept WASM_SPEC_REPO / WASM_TESTSUITE_REPO / WASMTIME_REPO / WASM_PROPOSAL_ROOT overrides —