33eff7c7d8
Rename src/jolt -> stdlib (the runtime-loaded layer; jolt-core stays the seed-baked layer) and update the loader / emit-image / doc paths. Drop dead code: the spike/ experiments, the duplicate clojuredocs-export.edn (json moves to tools/), the Janet-era jolt.http binding, and the orphaned persistent_vector.clj whose ns/path didn't even match. Strip porting residue from comments and docstrings across host/chez, jolt-core, stdlib, tests, and docs: internal issue ids, "Phase N" markers, and the "vs Janet" historical exposition, leaving present-tense descriptions and the real JVM-Clojure semantic contrasts. Same pass over the corpus suite labels. The seed is unchanged (docstrings/comments aren't emitted), so the self-host fixpoint and corpus are untouched. Port tools/spec_coverage.py off the dead janet probe to bin/joltc and regenerate coverage.md; drop the dead :host/janet rule from certify.clj and regenerate the conformance profile. Add docs/host-interop.md (the JVM shims and how to register your own host class from a library) and a writing-style note in CLAUDE.md. Stabilize the four racy concurrency corpus cases (future-cancel and agent send/send-off): give the future a sleeping body and the agent a slow action, so cancel reliably catches an in-flight future and deref reliably reads the pre-update snapshot. They certify deterministically now, so drop their :flaky allowlist entries and the orphaned legend.
132 lines
6.3 KiB
Markdown
132 lines
6.3 KiB
Markdown
# Project Instructions for AI Agents
|
|
|
|
This file provides instructions and context for AI coding agents working on this project.
|
|
|
|
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:7510c1e2 -->
|
|
## Beads Issue Tracker
|
|
|
|
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
|
|
|
### Quick Reference
|
|
|
|
```bash
|
|
bd ready # Find available work
|
|
bd show <id> # View issue details
|
|
bd update <id> --claim # Claim work
|
|
bd close <id> # Complete work
|
|
```
|
|
|
|
### Rules
|
|
|
|
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
|
- Run `bd prime` for detailed command reference and session close protocol
|
|
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
|
|
|
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
|
|
|
|
## Session Completion
|
|
|
|
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
|
|
|
|
**MANDATORY WORKFLOW:**
|
|
|
|
1. **File issues for remaining work** - Create issues for anything that needs follow-up
|
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
|
3. **Update issue status** - Close finished work, update in-progress items
|
|
4. **PUSH TO REMOTE** - This is MANDATORY:
|
|
```bash
|
|
git pull --rebase
|
|
git push
|
|
git status # MUST show "up to date with origin"
|
|
```
|
|
5. **Clean up** - Clear stashes, prune remote branches
|
|
6. **Verify** - All changes committed AND pushed
|
|
7. **Hand off** - Provide context for next session
|
|
|
|
**CRITICAL RULES:**
|
|
- Work is NOT complete until `git push` succeeds
|
|
- NEVER stop before pushing - that leaves work stranded locally
|
|
- NEVER say "ready to push when you are" - YOU must push
|
|
- If push fails, resolve and retry until it succeeds
|
|
<!-- END BEADS INTEGRATION -->
|
|
|
|
|
|
## Build & Test
|
|
|
|
No build step — `bin/joltc` runs off the checked-in seed (`host/chez/seed/`).
|
|
The gate is pure Chez (+ Clojure for the JVM oracle).
|
|
|
|
```bash
|
|
bin/joltc -e EXPR # run a Clojure expression on Chez
|
|
make test # FULL gate (self-host + corpus + unit + smoke + certify)
|
|
make corpus # conformance corpus vs the JVM-sourced spec (floor 2678)
|
|
make unit # host-specific unit cases (test/chez/unit.edn)
|
|
make selfhost # bootstrap fixpoint (rebuild == checked-in seed)
|
|
make certify # JVM oracle (skips if clojure absent)
|
|
chez --script host/chez/run-corpus.ss # the corpus gate directly; JOLT_CORPUS_LIMIT=N for a fast stride
|
|
make remint # re-mint the seed after a seed-source change
|
|
```
|
|
|
|
**Re-mint after changing a seed source.** The reader (`host/chez/reader.ss`), the
|
|
analyzer/IR/backend (`jolt-core/jolt/*.clj`), or the `clojure.core` overlay
|
|
(`jolt-core/clojure/core/*.clj`) are baked into the seed — change one and run
|
|
`make remint` (iterates `host/chez/bootstrap.ss` to a byte-fixpoint) or `make
|
|
selfhost` fails. Runtime-only `host/chez/*.ss` shims do NOT need a re-mint.
|
|
|
|
**Run the gate with a REAL exit code.** `make test > /tmp/gate.out 2>&1; echo
|
|
"EXIT: $?"` — the final `OK: all gates passed` line must be present. CI
|
|
(`.github/workflows/tests.yml`) runs `make test` on every push/PR.
|
|
|
|
## Architecture Overview
|
|
|
|
Clojure on Chez Scheme — the sole substrate. A small Chez runtime
|
|
(`host/chez/*.ss`: value model, persistent collections, seqs, vars/ns, host
|
|
interop) hosts a portable Clojure overlay (`jolt-core/`): the
|
|
reader/analyzer/IR/backend (`jolt-core/jolt/`) and `clojure.core` in
|
|
dependency-ordered tiers (`jolt-core/clojure/core/NN-*.clj`, loaded in order:
|
|
00-syntax, 00-kernel, 10-seq, 20-coll, 25-sorted, 30-macros, 40-lazy, 50-io).
|
|
The stdlib namespaces (`clojure.string`/`set`/`walk`/`edn`/`pprint`/…) are
|
|
portable Clojure under `stdlib/clojure/`.
|
|
|
|
`bin/joltc` (`host/chez/cli.ss`) loads the checked-in seed
|
|
(`host/chez/seed/{prelude,image}.ss`) + the spine and compiles+evals on Chez
|
|
(read → analyze → IR → emit → eval). `host/chez/bootstrap.ss` rebuilds that seed
|
|
from source on pure Chez; the build is a self-hosting fixpoint (a rebuild
|
|
reproduces the checked-in seed byte-for-byte — `make selfhost`). The correctness
|
|
oracle is the JVM-sourced conformance corpus (`test/chez/corpus.edn`,
|
|
`test/conformance/`).
|
|
|
|
Issue tracking and design notes live in beads (`bd prime`, `bd memories`).
|
|
|
|
## Conventions & Patterns
|
|
|
|
- **A tier may only use macros from tiers that load before it.** Compile mode
|
|
expands macros at tier LOAD, so an `if-let` (30-macros) inside a 20-coll fn
|
|
breaks compiled init even though it passes when expanded lazily. Same ordering
|
|
for expander-called fns (empty?/keys/vals live in 00-syntax).
|
|
- **Never read your own wrapper's fields with `get`** in attached-ops values
|
|
(sorted colls): `get` on the wrapper IS the dispatched lookup and recurses
|
|
forever. Use `jolt.host/ref-get`.
|
|
- **Map literals with `:jolt/type` as a key** parse as tagged reader forms —
|
|
don't tag overlay value maps in source.
|
|
- **Fix latent bugs to match Clojure** rather than preserving them, with a
|
|
regression case. Match the JVM (or provide a superset); the JVM-sourced corpus
|
|
is the contract.
|
|
- **Gate every change**: `make test` with a real exit code (self-host fixpoint,
|
|
corpus floor, unit, cli smoke, certify). Re-mint if a seed source changed.
|
|
|
|
## Writing style (comments, docstrings, docs)
|
|
|
|
Write like a human maintainer of a serious open-source project. Plain, terse,
|
|
factual. Document how the code works *now* — what it does and why it matters.
|
|
|
|
- No LLM tells: drop "Note that", "It's worth noting", "Importantly", "simply",
|
|
"essentially", "in order to", "under the hood", and marketing words
|
|
("comprehensive", "robust", "seamless", "leverage", "powerful").
|
|
- No historical exposition (how the code used to work, porting notes, "the prior
|
|
X"), no internal issue IDs (`jolt-xxxx`) or milestone tags ("Phase N") in
|
|
comments or docstrings. The git history and beads hold that.
|
|
- Keep genuine semantic contrasts with JVM Clojure — those document real,
|
|
user-visible behavior.
|
|
- Don't restate the code; explain the non-obvious. Match the surrounding file's
|
|
comment density and tone.
|