chore(config): SessionStart toolchain hook + Phase-3 state note (Refs #57)#482
Merged
Conversation
…57) Wrap-up for the res-to-affine Phase 3 work (slices 1 #477 + 2 #481). - .claude/hooks/session-start.sh — SessionStart hook provisioning the OCaml toolchain (apt: dune / cmdliner / fmt / alcotest / menhir / sedlex / ppx_deriving / ppxlib / yojson / js_of_ocaml), the tree-sitter CLI, and the pinned tree-sitter-rescript grammar, so web sessions can `dune build` / `dune runtest` without manual setup. apt (not opam) because opam.ocaml.org is network-blocked here while Ubuntu's packages match the project's version pins. Synchronous, idempotent, best-effort, web-only (CLAUDE_CODE_REMOTE). - .claude/settings.json — register the hook; add dune / tree-sitter build+test permissions (existing read-only allowlist preserved). - STATE.a2ml — dated session note documenting Phase 3 slices 1+2, the conservative design, the qualified-path deferral, and the local build / test / compiler-oracle verification. Validated locally: full `dune build` exit 0; `dune runtest tools/res-to-affine/` green; doc-truthing + no-extension-ts guards pass; hook runs clean on the idempotent path. Refs #57 https://claude.ai/code/session_017T8SzHr2yXav8hm4Ho76Uw
This was referenced May 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Wrap-up for the res-to-affine Phase 3 work (slices 1 #477 + 2 #481): a SessionStart hook so web sessions can build/test this project without manual setup, plus state documentation.
Changes
.claude/hooks/session-start.sh— SessionStart hook provisioning the OCaml toolchain via apt (ocaml-nox ocaml-dune ocaml-findlib,libcmdliner/libfmt/libalcotest,menhir/libmenhir/libsedlex,libppx-deriving/libppxlib/libyojson,js-of-ocaml/libjs-of-ocaml-dev), the tree-sitter CLI (npm i -g tree-sitter-cli@^0.25.0), and the pinned tree-sitter-rescript grammar (editors/tree-sitter-rescript/scripts/install.sh). apt rather than opam becauseopam.ocaml.orgis blocked by this environment's network policy (403), while Ubuntu's packages happen to match the project's version pins — this exact set was verified to give a clean fulldune build. Synchronous, idempotent (skips ifdune/tree-sitter/parser.calready present), best-effort (a failed step warns to stderr, never aborts session start), web-only (CLAUDE_CODE_REMOTEguard)..claude/settings.json— registers the hook underhooks.SessionStart; addsdune build/runtest/exec/test+tree-sitterto the permission allowlist. The existing read-only allowlist is preserved verbatim.STATE.a2ml— dated session note documenting Phase 3 slices 1+2, the conservative skip-don't-guess design, the qualified-path-RHS deferral (parses post-LANG: type/effect grammar has no module-qualified path —Pkg.Type/Pkg.Effectunrepresentable (estate-wide port blocker; ADR-014) #228 but won't resolve against a non-existent module), and the local build/test/oracle verification. Mirror keys (authoritative-status-doc/drift-flag) untouched, so the doc-truthing guard stays green.Validation (local, apt-bootstrapped toolchain)
node -e JSON.parse(settings.json)CLAUDE_CODE_REMOTE=true)bash -n session-start.shdune builddune runtest tools/res-to-affine/./tools/check-doc-truthing.sh./tools/check-no-extension-ts.shNo OCaml source touched — config + docs only, so the
build/migration-assistantjobs are unaffected. Known-baseline checks (vscode-smoke, the governance TS-exemption flag, Hypatia) remain pre-existing and unrelated.Hook execution mode: synchronous
Guarantees the toolchain is ready before the session begins (no race where Claude runs
dunebefore deps exist); cost is a one-time install on the first session (the container caches afterward). Can switch to async if you'd prefer faster startup. Once this lands onmain, all future web sessions use it.Refs #57https://claude.ai/code/session_017T8SzHr2yXav8hm4Ho76Uw
Generated by Claude Code