Unify AGENTS.md with canonical jerboa version
ober
7117a6e7375e5013f9d48cfc7d09d6c27a3bf8ce
--- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ Every Jerboa file looks like this: (displayln (my-function 1 2)) ``` -Run with: `scheme --libdirs lib --script file.ss` +Run with: `jerboa run file.ss` **NEVER** write `(library ...)` forms — that's `.sls` internal syntax. @@ -90,7 +90,7 @@ The following names from other Scheme dialects are aliased in `(jerboa prelude)` - `(string-split str delimiter)` where delimiter is a CHAR: `(string-split "a,b" #\,)` - `(make-rwlock)` — takes **0 args**, NOT `(make-rwlock 'name)` (Gerbil takes a name; Jerboa does not) - `(path-expand path)` — takes **1 arg**, NOT `(path-expand rel base)` (Gerbil takes 2; use `path-join` for 2-arg) -- `(sort predicate list)` — Chez arg order. NOT `(sort list predicate)` which is Gerbil/SRFI order +- `(sort list predicate)` — Jerboa `(std sort)`/prelude order. Raw Chez `sort` is predicate-first, but Jerboa-facing code should use list first. ### Core Forms (all from `(import (jerboa prelude))`) @@ -340,7 +340,8 @@ improved versions of the above. When working in a Jerboa project, **ONLY modify files in the current repo** unless the user explicitly names another path. Common sibling repos that exist but must NOT be touched without explicit instruction: -- `~/mine/jerboa-mcp` — Only modify when user explicitly says to work there. +- `~/mine/jerboa-emacs` — **NEVER touch**. Another model owns it. +- `~/mine/jerboa-mcp` — Legacy node MCP, superseded. The active MCP server now lives in THIS repo at `mcp/` + `data/`. Don't modify the legacy repo unless told. - `~/mine/jerboa-shell` — Only modify when user explicitly says to work there. - `~/mine/gerbil-mcp` — **NEVER touch**. Deprecated. - `~/mine/gerbil-orig` — Read-only reference for upstream Gerbil. Never modify. @@ -361,6 +362,22 @@ find lib -name "*.so" -delete && find lib -name "*.wpo" -delete && make build ``` Run `jerboa_stale_static` to detect stale `.so` files before debugging "why doesn't my edit work?". +## Pre-commit Requirements + +**ALWAYS** run a clean build **before** committing any code to this repository. Pick the right target for the *current* platform: + +- **Linux**: run `make docker-build` — the Docker image must build cleanly against the full musl-static release pipeline. +- **macOS / FreeBSD / other**: run `make binary` — the native local build must succeed. Do **not** run `make docker-build` here; Docker on non-Linux hosts is slow and not the canonical pipeline for those platforms. + +Do not commit if the build fails. + +## Act First, Read Less + +When making changes, read only what you need to make the edit, then make it. +Do not read more than 3 files before acting. Do not re-read files you already +read. Do not verify things you already know. If you have enough context to make +a change, make it. The user will interrupt you if you are wrong. + ## Jerboa MCP Tools — MANDATORY Usage Jerboa is a niche Scheme dialect with limited training data. **Never guess — always verify** with MCP tools. Tool descriptions are available at runtime via the MCP server; this section covers **when** and **why** to use each tool. @@ -388,7 +405,7 @@ Jerboa is a niche Scheme dialect with limited training data. **Never guess — a | Find where something is defined | `jerboa_find_definition` — source file, module, kind, arity | | Search for symbol by substring | `jerboa_apropos` or `jerboa_smart_complete` | | Build the project | `jerboa_build_and_report` or `jerboa_make` — prefer over bash `make` | -| Run tests | `jerboa_run_tests` — prefer over bash `scheme --script` | +| Run tests | `jerboa_run_tests` — prefer over ad hoc shell test invocations | | Check for stale .so artifacts | `jerboa_stale_static` — common cause of "edit has no effect" | | Macro expansion | `jerboa_expand_macro` / `jerboa_trace_macro` | | Inspect struct/class types | `jerboa_class_info` — fields, inheritance, constructor signature | @@ -408,6 +425,9 @@ Jerboa is a niche Scheme dialect with limited training data. **Never guess — a - **`jerboa_howto_add`**: Save new patterns to cookbook (MANDATORY when you discover something non-trivial) - **`jerboa_howto_run`** / **`jerboa_howto_verify`**: Validate recipes still work - **`jerboa_error_fix_add`**: Save error→fix mappings for common mistakes +- **`jerboa_anti_pattern_lookup`**: Search reusable local-model mistakes and failed strategies + +**The knowledge base is `data/*.sexp` in THIS repo**, embedded into `jmcp` at build time. The write tools above edit it live — the server reads `data/` from disk first, with the embedded copy as fallback (`JERBOA_MCP_REPO` points every client at this repo). When you add a stdlib/language feature, also update `data/` (a cookbook recipe + `api-signatures.sexp` + `changelog.sexp`) and **commit it**. Run `make jmcp` (or `make jmcp-portable`) only to refresh the embedded copy shipped in portable binaries. ### Code Generation & Refactoring @@ -432,6 +452,25 @@ Jerboa is niche — every non-trivial pattern you discover prevents future sessi **Recipe format**: `id` (kebab-case), `tags` (4-6 search keywords incl. module name), `imports` (all required), `code` (complete working example), `notes` (gotchas/alternatives). +### Save anti-patterns (`data/anti-patterns.sexp`) whenever you: +- See a plausible local-model strategy that failed verification +- Find a weak verifier pattern that allowed false success +- See a repeated repair loop, such as broad-reading after a concrete error +- Find a generic runtime mistake, such as missing lower-bound checks before vector access + +**Before saving**: check `jerboa_anti_pattern_lookup` to avoid duplicates. If none exists, call `jerboa_anti_pattern_add`; only edit `data/anti-patterns.sexp` directly if the writer tool is unavailable. Save the normalized reusable mistake, not the whole trace or benchmark name. + +**Anti-pattern format**: `id`, `title`, `kinds`, `severity`, `tags`, `pattern`, `avoid`, `advice`, `tools`. + +### Save error fixes (`jerboa_error_fix_add`) whenever you: +- See exact compiler/runtime/verifier text with a repeatable repair +- Hit an error that `jerboa_failure_advisor` should classify better next time +- Debug a local-model generated-code failure where a short diagnosis prevents another failed iteration + +**Before saving**: check `jerboa_error_fix_lookup` with the exact error text. **Do NOT save**: one-off project business-logic mistakes. + +**Error-fix format**: `id`, `pattern`, `fix`; optional `type`, `explanation`, `code_example`. + ### Suggest tooling improvements (`jerboa_suggest_feature`) whenever you: - Make multiple sequential tool calls that could be one tool - Fall back to bash because an MCP tool is missing or insufficient @@ -439,7 +478,7 @@ Jerboa is niche — every non-trivial pattern you discover prevents future sessi **Before suggesting**: check `jerboa_list_features`; vote with `jerboa_vote_feature` if it already exists. ### Save Discoveries Mechanisms -- **`/save-discoveries` skill**: invoke anytime to review session and save patterns + suggestions +- **`/save-discoveries` skill**: invoke anytime to review session and save recipes, anti-patterns, error fixes, feature suggestions, and security patterns - **PreCompact hook**: add `PreCompact` hook with `type: "prompt"` in `.claude/settings.json` to auto-save before context compaction ---