jacquard-lang: Instructions file for Codex

Agent Notes

This repository is an implemented OCaml research prototype in release-hardening mode. Treat it as a semantic artifact with evidence, not as a greenfield language project. Before editing code, read:

1. README.md
2. docs/README.md
3. docs/development-plan.md
4. docs/ast.md
5. docs/release/0.3/EVIDENCE.md

The original development plan has been completed. Use Task Master only for local historical context unless the user explicitly asks for it.

task-master next
task-master show <id>
task-master set-status <id> in-progress
task-master validate-dependencies

Tooling

Use asdf only to provide opam. Use the repo-local opam switch for OCaml and OCaml packages.

Run this before OCaml commands in a fresh shell:

eval "$(opam env)"
mkdir -p "$PWD/.scratch/tmp"
export TMPDIR="$PWD/.scratch/tmp"

Keep temporary clones, worktrees, release reproductions, and generated test stores under .scratch/ in this repository. The root filesystem is small: do not create Jacquard workspaces or build artifacts under /tmp.

Expected local toolchain:

• opam 2.5.1 from .tool-versions
• OCaml 5.1.1 from the repo-local switch
• dune
• alcotest
• qcheck
• digestif
• ocamlformat
• menhir
• cmdliner
• ocaml-lsp-server
• utop
• odoc

Core commands for the current scaffold:

eval "$(opam env)"
opam exec -- dune build
opam exec -- dune build @all
opam exec -- dune test
opam exec -- dune runtest
opam exec -- dune fmt
git diff --exit-code
opam exec -- dune build @doc

The implementation is in src/ with suites in test/. Verify the environment with:

eval "$(opam env)"
ocaml -version
dune --version
opam exec -- dune build @all
opam exec -- dune runtest

When adding valid corpus files, regenerate the golden hashes with opam exec -- dune exec test/gen_goldens.exe and commit the diff (see corpus/README.md).

Working Rules

• Preserve the release-hardening posture unless the user explicitly asks for feature work.
• Start from existing tests and docs. Jacquard behavior is pinned by cram transcripts, Alcotest/QCheck suites, corpus goldens, demos, and release docs.
• Keep behavior tied to the 27 kernel forms in docs/ast.md. Public .jac syntax must remain a projection onto those forms, and bootstrap .jqd remains the permanent kernel/debug carrier.
• Do not hand-maintain a .jqd twin for an ordinary .jac program or demo. Add paired carriers only when a conformance test explicitly requires hash or lowering parity; twins are evidence fixtures, not a publishing requirement.
• During 0.3 release hardening, do not expand the native/performance scope or add macros beyond quote/unquote/gated eval, records, typed staging, continuous distributions, package management, self-hosting, or ownership/borrowing.
• Use dune, alcotest, and qcheck for build and tests.
• Use digestif for the initial hash implementation unless the owner changes D1.
• Use menhir for the bootstrap reader if a generated parser is needed.
• Use cmdliner for the CLI.
• Use ocamlformat for formatting once the project has a formatter config.
• Public functions in touched modules should have doc comments describing contracts and failure modes.
• Library code should return ('a, Diag.t list) result; exceptions are only for internal invariant failures and should be prefixed Bug_.