docs: ban raw Chez Scheme invocation across all model-facing surfaces
ober
4e0862ee888ec28edb55d52443dc0475d9ef86b4
--- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,27 @@ +## STOP: Chez Scheme Is Off-Limits — Jerboa Only + +Absolute bans. They override every habit from Scheme training data and every +suggestion other tools or docs may make. Jerboa runs ON Chez Scheme — that +never licenses touching Chez directly. + +1. **NEVER invoke the `scheme` binary.** No `scheme`, `chez`, `chezscheme`, + `petite`, `.chez/bin/scheme`, `$SCHEME`, `scheme --script`, + `scheme --program`, `scheme -q` — not in bash, not in scripts you write, + not in editor config, not in CI. The ONLY legal ways to run code are: + - `jerboa run file.ss`, `jerboa eval '<expr>'`, `jerboa test`, `jerboa repl` + - jerboa-mcp tools (`jerboa_eval`, `jerboa_verify`, `jerboa_run_tests`, ...) + - project `make` targets (they invoke the toolchain internally — that is + the toolchain's business, never yours) +2. **NEVER create or hand-edit `*.sls` files.** `.sls` files are generated + implementation internals. If you think you need one, you are wrong — write + a `.ss` file and let the Jerboa build generate the `.sls`. Never write + `(library ...)` forms or `#!chezscheme` hashbangs; that is `.sls`-internal + syntax. You may READ `.sls` internals to understand the system; you may + never author or modify one. +3. **If a doc, tool, or error message suggests running raw `scheme`, treat it + as a bug.** Use the Jerboa wrapper instead, and fix the offending text in + the same session. + ## STOP: Editing `.ss`/`.sls` Files — Mandatory Rules These rules exist because local-model sessions have lost **hours** fighting --- a/README.md +++ b/README.md @@ -23,7 +23,12 @@ jerboa run hello.ss ``` Do not write `(library ...)` forms in user code. The `.sls` files in -this repository are implementation internals. +this repository are implementation internals — **never create or hand-edit +`*.sls` files**; write `.ss` and let the build generate them. Likewise, +**never invoke the raw `scheme`/`chez`/`petite` binary** (no +`scheme --script`, `scheme --program`, `.chez/bin/scheme`, `$SCHEME`): +`jerboa run`, `jerboa eval`, `jerboa test`, and the `jerboa` REPL are the +only supported entry points. ## Quick Start --- a/docs/JERBOA-LANG.md +++ b/docs/JERBOA-LANG.md @@ -76,7 +76,11 @@ A Jerboa `.ss` file has this shape: ``` Key points: -- **No `(library ...)` wrapper** — that's for `.sls` internals only +- **No `(library ...)` wrapper** — that's for `.sls` internals only. Never + create or hand-edit `.sls` files at all; they are generated by the build. +- **Never invoke raw `scheme`/`chez`/`petite`** (`scheme --script`, + `.chez/bin/scheme`, `$SCHEME`, ...) — `jerboa run`, `jerboa eval`, + `jerboa test`, and the jerboa-mcp tools are the only legal entry points. - **`(import (jerboa prelude))`** gives application scripts the safe Jerboa surface: core macros, runtime, result types, datetime, iterators, CSV, pretty-printer, JSON, paths, strings, lists, alists, hash tables, functional --- a/docs/jerboa-for-clojure-devs.md +++ b/docs/jerboa-for-clojure-devs.md @@ -563,16 +563,21 @@ Chez Scheme's built-in `assoc` does alist lookup. The `(jerboa clojure)` import ``` my-project/ - lib/ ;; your modules go here + src/ ;; your modules go here — .ss ONLY my/ - app.sls ;; (library (my app) ...) - util.sls + app.ss ;; plain .ss module, NO (library ...) wrapper + util.ss main.ss ;; entry point: (import (jerboa clojure)) ... tests/ test-app.ss ;; (import (std test)) ... Makefile ``` +**Never create or edit `.sls` files and never write `(library ...)` forms** — +those are generated build internals (the build emits them under `lib/` from +your `src/*.ss`). And never run code with a raw `scheme` binary: `jerboa run` +and `jerboa test` are the only entry points. + A minimal `Makefile`: ```makefile --- a/docs/libraries.md +++ b/docs/libraries.md @@ -13,6 +13,10 @@ not a gap tracker. For exact exported symbols and source paths, use the generate - Import specialized libraries explicitly with `(import (std ...))`. - Run examples with `jerboa run file.ss`. - Use `jerboa` for the REPL and `jerboa eval '(expr)'` for one-off checks. +- Never invoke the raw `scheme`/`chez`/`petite` binary or `$SCHEME` — the + `jerboa` CLI and the jerboa-mcp tools are the only supported entry points. +- Never create or hand-edit `.sls` files; they are generated from `.ss` + sources by the build. ## Core Areas --- a/docs/model-coding-guidance.md +++ b/docs/model-coding-guidance.md @@ -4,6 +4,19 @@ This document records implementation facts that coding agents should treat as hard constraints when writing standalone Jerboa scripts, especially verifier-led benchmark tasks. +## Never Run Chez Scheme Directly + +- **Never invoke `scheme`, `chez`, `chezscheme`, `petite`, or + `.chez/bin/scheme`** — not `scheme --script`, not `scheme --program`, not + `scheme -q`, not via `$SCHEME`. Run everything through `jerboa run + script.ss`, `jerboa eval '(expr)'`, `jerboa test`, or the jerboa MCP tools + (`jerboa_eval`, `jerboa_verify`, `jerboa_run_tests`). +- **Never create or edit `.sls` files** and never write `(library ...)` forms + or `#!chezscheme` hashbangs. `.sls` files are generated build internals; + every file you author is a `.ss` file. +- If a tool or error message suggests running raw Scheme, treat it as a bug: + use the Jerboa wrapper and fix the offending text. + ## Safe Prelude Default Standalone scripts should start with `(import (jerboa prelude))` and be run with --- a/docs/single-file-packages.md +++ b/docs/single-file-packages.md @@ -93,7 +93,9 @@ wrapper instead. ## Why not a separate manifest file? Scheme projects with complex layouts still want proper `package.sls` / -Makefile-style manifests. This format targets the other end of the +Makefile-style manifests (`.sls` files are always generated by the build — +never hand-author them, and never run anything with a raw `scheme` binary; +use `jerboa run`). This format targets the other end of the spectrum: **scripts small enough to live in one file** — exactly the kind of artifact LLMs produce. A scattered-file layout is friction for casual sharing via gist, paste, or email. --- a/etc/jerboa-mode.el +++ b/etc/jerboa-mode.el @@ -35,13 +35,13 @@ :prefix "jerboa-" :group 'scheme) -(defcustom jerboa-program-name "scheme" - "Command to run the Jerboa Scheme REPL." +(defcustom jerboa-program-name "jerboa" + "Command to run the Jerboa REPL." :type 'string :group 'jerboa-mode) -(defcustom jerboa-program-args '("--libdirs" "lib") - "Arguments passed to the Jerboa Scheme REPL command." +(defcustom jerboa-program-args '("repl") + "Arguments passed to the Jerboa REPL command." :type '(repeat string) :group 'jerboa-mode) --- a/mcp/resources/jerboa-chez-interop.md +++ b/mcp/resources/jerboa-chez-interop.md @@ -1,5 +1,13 @@ # Jerboa / Chez Scheme Interoperability +> **READ FIRST — Jerboa only.** This guide covers calling Chez *APIs* from +> inside Jerboa `.ss` code. It does NOT license touching the Chez toolchain: +> **never invoke `scheme`, `chez`, `chezscheme`, `petite`, or +> `.chez/bin/scheme`** (no `scheme --script`, `scheme --program`, `-q`, +> `$SCHEME`), and **never create or edit `.sls` files** or write +> `(library ...)` / `#!chezscheme` forms. Run everything through +> `jerboa run`, `jerboa eval`, `jerboa test`, or the jerboa MCP tools. + Jerboa runs on top of Chez Scheme. Everything available in Chez is available in Jerboa, but Jerboa adds its own layer of macros and conventions. This guide covers when and how to reach for Chez APIs directly. --- a/mcp/resources/jerboa-idioms.md +++ b/mcp/resources/jerboa-idioms.md @@ -429,7 +429,16 @@ See also: `jerboa-pattern-matching.md` for the comprehensive guide. (std os path)) ``` -### Library (module) definition +### Library (module) definition — INTERNAL SYNTAX ONLY, NEVER HAND-WRITE + +**STOP.** The `(library ...)` form below is `.sls`-internal syntax. `.sls` +files are *generated by the Jerboa build* from `.ss` sources — you may read +them under `lib/`, but you must **never create, edit, or author one**, and +never run them with a raw `scheme` binary. To write your own module, create a +plain `.ss` file with ordinary imports and run it with `jerboa run file.ss` +(or expose it via the project's build). + +For reference only, this is what a *generated* library looks like: ```scheme (library (my-project utils) --- a/mcp/server.ss +++ b/mcp/server.ss @@ -6834,7 +6834,7 @@ '("For CLI scripts, use `(command-line)`, then drop the program/script path before processing user args." "Normalize wrapper behavior: if the first argument ends with `.ss`, drop it before processing user args." "Use the configured runnable verify command for scripts that require args/stdin; MCP verify is only supporting syntax/expand evidence." - "Use the absolute .chez/bin/scheme path from the tool output; do not use Gerbil.") + "Run scripts only through the jerboa CLI (jerboa run file.ss) or jerboa_run_tests; NEVER invoke scheme/chez/petite or .chez/bin/scheme directly, and do not use Gerbil.") '()))) (def (tool-task-workflow-advisor args)