diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index bc2ae10..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,96 +0,0 @@ -# Agent Instructions - -This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context. - -> **Architecture in one line:** Issues live in a local Dolt database -> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a -> git-compatible protocol), stored under `refs/dolt/data` on your git -> remote — separate from `refs/heads/*` where your code lives. -> `.beads/issues.jsonl` is a passive export, not the wire protocol. -> -> See [SYNC_CONCEPTS.md](https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md) -> for the one-screen overview and anti-patterns (don't treat JSONL as the -> source of truth; don't `bd import` during normal operation; don't -> reach for third-party Dolt hosting before trying the default). - -## Quick Reference - -```bash -bd ready # Find available work -bd show # View issue details -bd update --claim # Claim work atomically -bd close # Complete work -bd dolt push # Push beads data to remote -``` - -## Non-Interactive Shell Commands - -**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts. - -Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input. - -**Use these forms instead:** -```bash -# Force overwrite without prompting -cp -f source dest # NOT: cp source dest -mv -f source dest # NOT: mv source dest -rm -f file # NOT: rm file - -# For recursive operations -rm -rf directory # NOT: rm -r directory -cp -rf source dest # NOT: cp -r source dest -``` - -**Other commands that may prompt:** -- `scp` - use `-o BatchMode=yes` for non-interactive -- `ssh` - use `-o BatchMode=yes` to fail instead of prompting -- `apt-get` - use `-y` flag -- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var - - -## 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 # View issue details -bd update --claim # Claim work -bd close # 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 - diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5a19465..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,166 +0,0 @@ -# Project Instructions for AI Agents - -This file provides instructions and context for AI coding agents working on this project. - - -## 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 # View issue details -bd update --claim # Claim work -bd close # 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 - - - -## 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`). - -## Library conformance - -When a real Clojure library's tests pass on Jolt, treat the docs/specs/tests -update as PART OF THE SAME WORK — not a follow-up. In the change that lands the -fixes: - -- **Add JVM-certified corpus rows** (`test/chez/corpus.edn`) for every general - gap the library shook out — the corpus is the executable contract. Verify each - via `make test`'s certify step. -- **List the library** in BOTH the in-repo `docs/libraries.md` AND the website - (`jolt-lang.github.io`, `resources/md/libraries.md`) — one line (name + a short - description + any load note like `JOLT_FEATURES` `clj`). Do NOT enumerate what - works or paste test tallies; a listed library is assumed to work fully, so only - list it once it does. -- **Update the affected prose docs and RFCs** — `docs/host-interop.md` for new - interop surface, `docs/spec/*.md` / `docs/rfc/*` for semantics, `docs/MODULES.md` - if files moved. -- **File a bead** for each remaining gap so it's tracked. - -The supported-libraries list (docs + site) and the corpus are the public record -of what Jolt runs — keep them current as libraries land. - -## 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. -- **The compiler is reached from the runtime by `var-deref` string lookup.** The - `.ss` runtime calls into the cross-compiled compiler with - `(var-deref "jolt.analyzer" "analyze")` etc., and the compiler resolves its own - unqualified `jolt.host/…` refs the same way against `host-contract.ss`. So a - public `defn` with no in-Clojure callers may still be a live entry point — don't - treat it as dead. Only a private `defn-` with no callers is safe to remove. -- **A native `clojure.core` fn is a `(def-var! "clojure.core" "name" …)`** in a - `host/chez/*.ss`; the rest of core is the overlay (`jolt-core/clojure/core/*.clj`). - A few natives are re-asserted in `post-prelude.ss` so they win over the overlay. - See [docs/MODULES.md](docs/MODULES.md) for where a given fn lives, and - [docs/seed-overlay-registry.md](docs/seed-overlay-registry.md) for the shadowing - rule. Start at [docs/MODULES.md](docs/MODULES.md) to find a feature's files. -- **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.