amr/memex

Files

Amr Gharbeia 888ef00728 passepartout: v0.4.2 Structured Output

Submodule: function-calling API, json-alist-to-plist converter,
tool-calls wiring in think(), diagnostics fix, version bump to 0.4.2.
AGENTS.md: validate with emacs check-parens on org source (not SBCL).

2026-05-07 17:39:21 -04:00

2.1 KiB

Raw Blame History

AGENTS.md

Development Cycle (every change)

Think in org — write your reasoning, goals, and approach in the .org file first
Write contract — define a ** Contract section listing each function's behavior: (fn-name args): description. Returns/guarantees ...
TDD from contract — each contract item becomes a fiveam:test in * Test Suite a. Write the test first → tangle → run → prove it FAILS (RED) b. Write the implementation → tangle → run → prove it PASSES (GREEN) c. Record both failure and success output
Reflect in org — once tests pass, ensure the implementation is in the .org source
Update literate prose — write/update the explanatory text around the code: what it does, why it exists, how it connects to the rest of the system
Commit — only when asked. Ask first.

Commands

Tangle a single file: emacs --batch --eval "(progn (require 'org) (find-file "org/FILE.org") (org-babel-tangle) (kill-buffer))"

Validate structural integrity: emacs --batch -Q --eval '(progn (find-file "org/FILE.org") (check-parens) (kill-buffer))'

Run tests: sbcl --noinform
--eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))'
--eval '(ql:quickload :passepartout :silent t)'
--eval '(load "lisp/FILE.lisp")'
--eval '(fiveam:run (intern "SUITE-NAME" :passepartout-TESTS))' --quit

For error details: bind fiveam:on-failure to :debug

REPL (port 9105) — preferred when available

Start: passepartout daemon Send code: msg = '(:type :event :payload (:sensor :repl-eval :code "(+ 1 2)"))' s.sendall(f'{len(msg):06x}'.encode() + msg.encode())

When REPL is up: TDD in-image first, then reflect to .org and tangle. When REPL is down: fall back to the SBCL cycle above.

Rules

.org is source of truth; .lisp is generated — never edit .lisp directly
Every code change starts with a contract and a failing test
Prove RED before writing implementation
Validate before committing
If a tool fails, explain why and ask before trying alternatives
Before shipping a version, run the ** File Update Checklist in docs/ROADMAP.org